diff --git a/docs/auth/cloudflare/access.md b/docs/auth/cloudflare/access.md index d47495180a..05663aca30 100644 --- a/docs/auth/cloudflare/access.md +++ b/docs/auth/cloudflare/access.md @@ -38,7 +38,7 @@ add the provider itself. Add a `providerFactories` entry to the router in `packages/backend/plugin/auth.ts`. -```ts +```ts title="packages/backend/plugin/auth.ts" import { providers } from '@backstage/plugin-auth-backend'; export default async function createPlugin( @@ -89,12 +89,18 @@ the user's behalf. It is recommended to use the `ProxiedSignInPage` for this provider, which is installed in `packages/app/src/App.tsx` like this: -```diff -+import { ProxiedSignInPage } from '@backstage/core-components'; +```tsx title="packages/app/src/App.tsx" +/* highlight-add-next-line */ +import { ProxiedSignInPage } from '@backstage/core-components'; - const app = createApp({ - components: { -+ SignInPage: props => , +const app = createApp({ + /* highlight-add-start */ + components: { + SignInPage: props => , + }, + /* highlight-add-end */ + // .. +}) ``` See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for pointers on how to set up the sign-in page to also work smoothly for local development. diff --git a/docs/auth/google/gcp-iap-auth.md b/docs/auth/google/gcp-iap-auth.md index 36eece85c5..138d795f0f 100644 --- a/docs/auth/google/gcp-iap-auth.md +++ b/docs/auth/google/gcp-iap-auth.md @@ -45,7 +45,7 @@ callbacks in actual code as well as described below. Add a `providerFactories` entry to the router in `packages/backend/src/plugins/auth.ts`. -```ts +```ts title="packages/backend/src/plugins/auth.ts" import { providers } from '@backstage/plugin-auth-backend'; import { stringifyEntityRef } from '@backstage/catalog-model'; @@ -99,12 +99,18 @@ sign-in mechanism to poll that endpoint through the IAP, on the user's behalf. It is recommended to use the `ProxiedSignInPage` for this provider, which is installed in `packages/app/src/App.tsx` like this: -```diff -+import { ProxiedSignInPage } from '@backstage/core-components'; +```tsx title="packages/app/src/App.tsx" +/* highlight-add-next-line */ +import { ProxiedSignInPage } from '@backstage/core-components'; - const app = createApp({ - components: { -+ SignInPage: props => , +const app = createApp({ + /* highlight-add-start */ + components: { + SignInPage: props => , + }, + /* highlight-add-end */ + // .. +}) ``` See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information. diff --git a/docs/auth/index.md b/docs/auth/index.md index 8e15830aa8..7f4511af24 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -84,49 +84,55 @@ which takes either a `provider` or `providers` (array) prop of `SignInProviderCo The following example for GitHub shows the additions needed to `packages/app/src/App.tsx`, and can be adapted to any of the built-in providers: -```diff -+ import { githubAuthApiRef } from '@backstage/core-plugin-api'; -+ import { SignInPage } from '@backstage/core-components'; +```tsx title="packages/app/src/App.tsx" +/* highlight-add-start */ +import { githubAuthApiRef } from '@backstage/core-plugin-api'; +import { SignInPage } from '@backstage/core-components'; +/* highlight-add-end */ - const app = createApp({ - apis, -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { +const app = createApp({ + /* highlight-add-start */ + components: { + SignInPage: props => ( + + ), + }, + /* highlight-add-end */ + // .. +}); ``` You can also use the `providers` prop to enable multiple sign-in methods, for example allows allowing guest access: -```diff - const app = createApp({ - apis, -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { +```tsx title="packages/app/src/App.tsx" +const app = createApp({ + /* highlight-add-start */ + components: { + SignInPage: props => ( + + ), + }, + /* highlight-add-end */ + // .. +}); ``` ## Sign-In with Proxy Providers @@ -142,12 +148,12 @@ All the sign-in page needs to do is to call the `/refresh` endpoint of the auth to get the existing session, which is exactly what the `ProxiedSignInPage` does. The only thing you need to do to configure the `ProxiedSignInPage` is to pass the ID of the provider like this: -```tsx +```tsx title="packages/app/src/App.tsx" const app = createApp({ - ..., components: { SignInPage: props => , }, + // .. }); ``` @@ -159,6 +165,7 @@ Example: ``` @@ -169,10 +176,12 @@ Headers can also be returned in an async manner: { const someValue = await someFn(); return { 'x-some-key': someValue }; }} + /* highlight-end */ /> ``` @@ -184,9 +193,8 @@ select the sign-in method based on the `process.env.NODE_ENV` environment variab by checking the `hostname` of the current location, or by accessing the configuration API to read a configuration value. For example: -```tsx +```tsx title="packages/app/src/App.tsx" const app = createApp({ - ..., components: { SignInPage: props => { const configApi = useApi(configApiRef); @@ -206,6 +214,7 @@ const app = createApp({ return ; }, }, + // .. }); ``` @@ -218,7 +227,7 @@ If you want to use the authentication capabilities of the [Repository Picker](.. To set it up, you'll need to add an API factory entry to `packages/app/src/apis.ts`. The example below sets up the `ScmAuthApi` for an already configured GitLab authentication provider: -```ts +```ts title="packages/app/src/apis.ts" createApiFactory({ api: scmAuthApiRef, deps: { @@ -294,23 +303,24 @@ If you require only a subset of these integrations, then you will need a custom The first step is to remove the code that creates the default providers. -```diff - import { - ScmIntegrationsApi, - scmIntegrationsApiRef, -+ ScmAuth, - } from '@backstage/integration-react'; +```ts title="packages/app/src/apis.ts" +import { + ScmIntegrationsApi, + scmIntegrationsApiRef, + /* highlight-add-next-line */ + ScmAuth, +} from '@backstage/integration-react'; - export const apis: AnyApiFactory[] = [ -... -+ ScmAuth.createDefaultApiFactory(), -... - ]; +export const apis: AnyApiFactory[] = [ + /* highlight-add-next-line */ + ScmAuth.createDefaultApiFactory(), + // ... +]; ``` Then replace it with something like this, which will create an `ApiFactory` with only a github provider. -```ts +```ts title="packages/app/src/apis.ts" export const apis: AnyApiFactory[] = [ createApiFactory({ api: scmAuthApiRef, diff --git a/docs/auth/microsoft/azure-easyauth.md b/docs/auth/microsoft/azure-easyauth.md index 3571a3e5c5..fb0b897760 100644 --- a/docs/auth/microsoft/azure-easyauth.md +++ b/docs/auth/microsoft/azure-easyauth.md @@ -60,12 +60,18 @@ sign-in mechanism to poll that endpoint through the IAP, on the user's behalf. It is recommended to use the `ProxiedSignInPage` for this provider, which is installed in `packages/app/src/App.tsx` like this: -```diff -+import { ProxiedSignInPage } from '@backstage/core-components'; +```tsx title="packages/app/src/App.tsx" +/* highlight-add-next-line */ +import { ProxiedSignInPage } from '@backstage/core-components'; - const app = createApp({ - components: { -+ SignInPage: props => , +const app = createApp({ + /* highlight-add-start */ + components: { + SignInPage: props => , + }, + /* highlight-add-end */ + // .. +}) ``` See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information. diff --git a/docs/auth/oauth2-proxy/provider.md b/docs/auth/oauth2-proxy/provider.md index ca3c40f5db..e3b5e89633 100644 --- a/docs/auth/oauth2-proxy/provider.md +++ b/docs/auth/oauth2-proxy/provider.md @@ -18,7 +18,7 @@ for more details check this The provider configuration can be added to your `app-config.yaml` under the root `auth` configuration: -```yaml +```yaml title="app-config.yaml" auth: providers: oauth2Proxy: {} @@ -63,12 +63,18 @@ providerFactories: { It is recommended to use the `ProxiedSignInPage` for this provider, which is installed in `packages/app/src/App.tsx` like this: -```diff -+import { ProxiedSignInPage } from '@backstage/core-components'; +```tsx title="packages/app/src/App.tsx" +/* highlight-add-next-line */ +import { ProxiedSignInPage } from '@backstage/core-components'; - const app = createApp({ - components: { -+ SignInPage: props => , +const app = createApp({ + /* highlight-add-start */ + components: { + SignInPage: props => , + }, + /* highlight-add-end */ + // .. +}) ``` See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for pointers on how to set up the sign-in page to also work smoothly for local development. diff --git a/docs/auth/oidc.md b/docs/auth/oidc.md index d915262eb7..0a9e4417ed 100644 --- a/docs/auth/oidc.md +++ b/docs/auth/oidc.md @@ -77,34 +77,39 @@ the instance is cached by the DI library, a singleton. Let's add our OIDC API factory to the APIs array in the `packages/app/src/apis.ts` file: -```diff -+ import { OAuth2 } from '@backstage/core-app-api'; +```ts title="packages/app/src/apis.ts" +/* highlight-add-next-line */ +import { OAuth2 } from '@backstage/core-app-api'; export const apis: AnyApiFactory[] = [ -+ createApiFactory({ -+ api: azureOIDCAuthApiRef, -+ deps: { -+ discoveryApi: discoveryApiRef, -+ oauthRequestApi: oauthRequestApiRef, -+ configApi: configApiRef, -+ }, -+ factory: ({ discoveryApi, oauthRequestApi, configApi }) => -+ OAuth2.create({ -+ discoveryApi, -+ oauthRequestApi, -+ provider: { -+ id: 'my-auth-provider', -+ title: 'My custom auth provider', -+ icon: () => null, -+ }, -+ environment: configApi.getOptionalString('auth.environment'), -+ defaultScopes: [ -+ 'openid', -+ 'profile', -+ 'email', -+ ], -+ }), -+ }), + /* highlight-add-start */ + createApiFactory({ + api: azureOIDCAuthApiRef, + deps: { + discoveryApi: discoveryApiRef, + oauthRequestApi: oauthRequestApiRef, + configApi: configApiRef, + }, + factory: ({ discoveryApi, oauthRequestApi, configApi }) => + OAuth2.create({ + discoveryApi, + oauthRequestApi, + provider: { + id: 'my-auth-provider', + title: 'My custom auth provider', + icon: () => null, + }, + environment: configApi.getOptionalString('auth.environment'), + defaultScopes: [ + 'openid', + 'profile', + 'email', + ], + }), + }), + /* highlight-add-end */ + // .. +] ``` @@ -125,7 +130,7 @@ the ID you picked to represent the Auth provider, this ID has to match with the callback URI provider segment (you'll have to configure your IDP to handle the callback URI properly). -```diff +```ts export default async function createPlugin( env: PluginEnvironment, ): Promise { @@ -137,9 +142,11 @@ export default async function createPlugin( tokenManager: env.tokenManager, providerFactories: { ...defaultAuthProviderFactories, -+ 'my-auth-provider': providers.oidc.create({ -+ }), - } + /* highlight-add-next-line */ + 'my-auth-provider': providers.oidc.create({}), + }, + // .. +}) ``` ### The Resolver @@ -154,10 +161,11 @@ adding a resolver for a SignIn request. The OIDC provider doesn't provide any build-in resolvers, so we'll need to define our own: -```diff +```ts import { DEFAULT_NAMESPACE, -+ stringifyEntityRef, + /* highlight-add-next-line */ + stringifyEntityRef, } from '@backstage/catalog-model'; export default async function createPlugin( @@ -172,23 +180,27 @@ export default async function createPlugin( providerFactories: { ...defaultAuthProviderFactories, 'my-auth-provider': providers.oidc.create({ -+ signIn: { -+ resolver(info, ctx) { -+ const userRef = stringifyEntityRef({ -+ kind: 'User', -+ name: info.result.userinfo.sub, -+ namespace: DEFAULT_NAMESPACE, -+ }); -+ return ctx.issueToken({ -+ claims: { -+ sub: userRef, // The user's own identity -+ ent: [userRef], // A list of identities that the user claims ownership through -+ }, -+ }); -+ }, -+ }, + /* highlight-add-start */ + signIn: { + resolver(info, ctx) { + const userRef = stringifyEntityRef({ + kind: 'User', + name: info.result.userinfo.sub, + namespace: DEFAULT_NAMESPACE, + }); + return ctx.issueToken({ + claims: { + sub: userRef, // The user's own identity + ent: [userRef], // A list of identities that the user claims ownership through + }, + }); + }, + }, + /* highlight-add-end */ }), - } + }, + // .. + }) ``` ### The configuration @@ -206,7 +218,7 @@ Then we need to configure the env variables for the provider, based on the provi in `plugins/auth-backend/src/providers/oidc/provider.ts` we need the following variables in the `app-config.yaml`: -```yaml +```yaml title="app-config.yaml" auth: environment: development ### Providing an auth.session.secret will enable session support in the auth-backend diff --git a/docs/auth/service-to-service-auth.md b/docs/auth/service-to-service-auth.md index 8d10fd7cc6..a667f391f5 100644 --- a/docs/auth/service-to-service-auth.md +++ b/docs/auth/service-to-service-auth.md @@ -23,9 +23,11 @@ that incoming requests are not validated. If you want to enable service-to-service auth, the first step is to switch out the following line in your backend setup at `packages/backend/src/index.ts`: -```diff -- const tokenManager = ServerTokenManager.noop(); -+ const tokenManager = ServerTokenManager.fromConfig(config, { logger: root }); +```ts title="packages/backend/src/index.ts" +/* highlight-remove-next-line */ +const tokenManager = ServerTokenManager.noop(); +/* highlight-add-next-line */ +const tokenManager = ServerTokenManager.fromConfig(config, { logger: root }); ``` By switching from the no-op `ServiceTokenManager` to one created from config, diff --git a/docs/backend-system/building-backends/08-migrating.md b/docs/backend-system/building-backends/08-migrating.md index 567476532f..358b6ae764 100644 --- a/docs/backend-system/building-backends/08-migrating.md +++ b/docs/backend-system/building-backends/08-migrating.md @@ -72,8 +72,7 @@ comment out its old contents, or renaming the old file to `index.backup.ts` for reference and making a new blank one to work on - whichever works best for you. These are our new blank contents in the index file: -```ts -// packages/backend/src/index.ts +```ts title="packages/backend/src/index.ts" import { createBackend } from '@backstage/backend-defaults'; const backend = createBackend(); @@ -95,13 +94,15 @@ backend start` command locally and seeing some logs scroll by. But it'll just be a blank service with no real features added. So let's stop it with `Ctrl+C` and reintroduce some plugins into the mix. -```diff - import { createBackend } from '@backstage/backend-defaults'; -+import { legacyPlugin } from '@backstage/backend-common'; +```ts title="packages/backend/src/index.ts" +import { createBackend } from '@backstage/backend-defaults'; +/* highlight-add-next-line */ +import { legacyPlugin } from '@backstage/backend-common'; - const backend = createBackend(); -+backend.add(legacyPlugin('todo', import('./plugins/todo'))); - backend.start(); +const backend = createBackend(); +/* highlight-add-next-line */ +backend.add(legacyPlugin('todo', import('./plugins/todo'))); +backend.start(); ``` The `todo` plugin used above is just an example and you may not have it enabled @@ -128,34 +129,39 @@ environment was changed from the defaults, perhaps with your own custom additions. If this is the case in your installation, you still aren't out of luck - you can build a customized `legacyPlugin` function. -```diff - import { createBackend } from '@backstage/backend-defaults'; --import { legacyPlugin } from '@backstage/backend-common'; -+import { makeLegacyPlugin, loggerToWinstonLogger } from '@backstage/backend-common'; -+import { coreServices } from '@backstage/backend-plugin-api'; +```ts title="packages/backend/src/index.ts" +import { createBackend } from '@backstage/backend-defaults'; +/* highlight-remove-next-line */ +import { legacyPlugin } from '@backstage/backend-common'; +/* highlight-add-start */ +import { makeLegacyPlugin, loggerToWinstonLogger } from '@backstage/backend-common'; +import { coreServices } from '@backstage/backend-plugin-api'; +/* highlight-add-end */ -+const legacyPlugin = makeLegacyPlugin( -+ { -+ cache: coreServices.cache, -+ config: coreServices.config, -+ database: coreServices.database, -+ discovery: coreServices.discovery, -+ logger: coreServices.logger, -+ permissions: coreServices.permissions, -+ scheduler: coreServices.scheduler, -+ tokenManager: coreServices.tokenManager, -+ reader: coreServices.urlReader, -+ identity: coreServices.identity, -+ // ... and your own additions -+ }, -+ { -+ logger: log => loggerToWinstonLogger(log), -+ }, -+); +/* highlight-add-start */ +const legacyPlugin = makeLegacyPlugin( + { + cache: coreServices.cache, + config: coreServices.config, + database: coreServices.database, + discovery: coreServices.discovery, + logger: coreServices.logger, + permissions: coreServices.permissions, + scheduler: coreServices.scheduler, + tokenManager: coreServices.tokenManager, + reader: coreServices.urlReader, + identity: coreServices.identity, + // ... and your own additions + }, + { + logger: log => loggerToWinstonLogger(log), + }, +); +/* highlight-add-end */ - const backend = createBackend(); - backend.add(legacyPlugin('todo', import('./plugins/todo'))); - backend.start(); +const backend = createBackend(); +backend.add(legacyPlugin('todo', import('./plugins/todo'))); +backend.start(); ``` The first argument to `makeLegacyPlugin` is the mapping from environment keys to @@ -177,13 +183,15 @@ in question. In this example, we'll assume that your added environment field is named `example`, and the created ref is named `exampleServiceRef`. -```diff -+import { exampleServiceRef } from ''; // if the definition is elsewhere +```ts title="packages/backend/src/index.ts" +/* highlight-add-next-line */ +import { exampleServiceRef } from ''; // if the definition is elsewhere const legacyPlugin = makeLegacyPlugin( { // ... the above core services still go here -+ example: exampleServiceRef + /* highlight-add-next-line */ + example: exampleServiceRef }, { logger: log => loggerToWinstonLogger(log), @@ -220,12 +228,13 @@ such migrations you can make. The app backend plugin that serves the frontend from the backend can trivially be used in its new form. -```diff - // packages/backend/src/index.ts -+import { appPlugin } from '@backstage/plugin-app-backend'; +```ts title="packages/backend/src/index.ts" +/* highlight-add-next-line */ +import { appPlugin } from '@backstage/plugin-app-backend'; - const backend = createBackend(); -+backend.add(appPlugin({ appPackageName: 'app' })); +const backend = createBackend(); +/* highlight-add-next-line */ +backend.add(appPlugin({ appPackageName: 'app' })); ``` This is an example of how options can be passed into some backend plugins. The @@ -239,14 +248,17 @@ You should be able to delete the `plugins/app.ts` file at this point. A basic installation of the catalog plugin looks as follows. -```diff - // packages/backend/src/index.ts -+import { catalogPlugin } from '@backstage/plugin-catalog-backend'; -+import { catalogModuleTemplateKind } from '@backstage/plugin-scaffolder-backend'; +```ts title="packages/backend/src/index.ts" +/* highlight-add-start */ +import { catalogPlugin } from '@backstage/plugin-catalog-backend'; +import { catalogModuleTemplateKind } from '@backstage/plugin-scaffolder-backend'; +/* highlight-add-end */ - const backend = createBackend(); -+backend.add(catalogPlugin()); -+backend.add(catalogModuleTemplateKind()); +const backend = createBackend(); +/* highlight-add-start */ +backend.add(catalogPlugin()); +backend.add(catalogModuleTemplateKind()); +/* highlight-add-end */ ``` Note that this also installs a module from the scaffolder, namely the one which @@ -262,34 +274,38 @@ mechanism to extend or tweak the functionality of the plugin. To do that, you'll make your own bespoke [module](../architecture/06-modules.md) which depends on the appropriate extension point and interacts with it. -```diff - // packages/backend/src/index.ts -+import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node'; -+import { createBackendModule } from '@backstage/backend-plugin-api'; +```ts title="packages/backend/src/index.ts" +/* highlight-add-start */ +import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node'; +import { createBackendModule } from '@backstage/backend-plugin-api'; +/* highlight-add-end */ -+const catalogModuleCustomExtensions = createBackendModule({ -+ pluginId: 'catalog', // name of the plugin that the module is targeting -+ moduleId: 'customExtensions', -+ register(env) { -+ env.registerInit({ -+ deps: { -+ catalog: catalogProcessingExtensionPoint, -+ // ... and other dependencies as needed -+ }, -+ init({ catalog /* ..., other dependencies */ }) { -+ // Here you have the opportunity to interact with the extension -+ // point before the plugin itself gets instantiated -+ catalog.addEntityProvider(new MyEntityProvider()); // just an example -+ catalog.addProcessor(new MyProcessor()); // just an example -+ }, -+ }); -+ }, -+}); +/* highlight-add-start */ +const catalogModuleCustomExtensions = createBackendModule({ + pluginId: 'catalog', // name of the plugin that the module is targeting + moduleId: 'customExtensions', + register(env) { + env.registerInit({ + deps: { + catalog: catalogProcessingExtensionPoint, + // ... and other dependencies as needed + }, + init({ catalog /* ..., other dependencies */ }) { + // Here you have the opportunity to interact with the extension + // point before the plugin itself gets instantiated + catalog.addEntityProvider(new MyEntityProvider()); // just an example + catalog.addProcessor(new MyProcessor()); // just an example + }, + }); + }, +}); +/* highlight-add-end */ - const backend = createBackend(); - backend.add(catalogPlugin()); - backend.add(catalogModuleTemplateKind()); -+backend.add(catalogModuleCustomExtensions()); +const backend = createBackend(); +backend.add(catalogPlugin()); +backend.add(catalogModuleTemplateKind()); +/* highlight-add-next-line */ +backend.add(catalogModuleCustomExtensions()); ``` This also requires that you have a dependency on the corresponding node package, @@ -310,12 +326,13 @@ implementations that they represent, and being exported from there. A basic installation of the events plugin looks as follows. -```diff - // packages/backend/src/index.ts -+import { eventsPlugin } from '@backstage/plugin-events-backend'; +```ts title="packages/backend/src/index.ts" +/* highlight-add-next-line */ +import { eventsPlugin } from '@backstage/plugin-events-backend'; - const backend = createBackend(); -+backend.add(eventsPlugin()); +const backend = createBackend(); +/* highlight-add-next-line */ +backend.add(eventsPlugin()); ``` If you have other customizations made to `plugins/events.ts`, such as adding @@ -327,32 +344,36 @@ mechanism to extend or tweak the functionality of the plugin. To do that, you'll make your own bespoke [module](../architecture/06-modules.md) which depends on the appropriate extension point and interacts with it. -```diff - // packages/backend/src/index.ts -+import { eventsExtensionPoint } from '@backstage/plugin-events-node'; -+import { createBackendModule } from '@backstage/backend-plugin-api'; +```ts title="packages/backend/src/index.ts" +/* highlight-add-start */ +import { eventsExtensionPoint } from '@backstage/plugin-events-node'; +import { createBackendModule } from '@backstage/backend-plugin-api'; +/* highlight-add-end */ -+const eventsModuleCustomExtensions = createBackendModule({ -+ pluginId: 'events', // name of the plugin that the module is targeting -+ moduleId: 'customExtensions', -+ register(env) { -+ env.registerInit({ -+ deps: { -+ events: eventsExtensionPoint, -+ // ... and other dependencies as needed -+ }, -+ init({ events /* ..., other dependencies */ }) { -+ // Here you have the opportunity to interact with the extension -+ // point before the plugin itself gets instantiated -+ events.addSubscribers(new MySubscriber()); // just an example -+ }, -+ }); -+ }, -+}); +/* highlight-add-start */ +const eventsModuleCustomExtensions = createBackendModule({ + pluginId: 'events', // name of the plugin that the module is targeting + moduleId: 'customExtensions', + register(env) { + env.registerInit({ + deps: { + events: eventsExtensionPoint, + // ... and other dependencies as needed + }, + init({ events /* ..., other dependencies */ }) { + // Here you have the opportunity to interact with the extension + // point before the plugin itself gets instantiated + events.addSubscribers(new MySubscriber()); // just an example + }, + }); + }, +}); +/* highlight-add-end */ - const backend = createBackend(); - backend.add(eventsPlugin()); -+backend.add(eventsModuleCustomExtensions()); +const backend = createBackend(); +backend.add(eventsPlugin()); +/* highlight-add-next-line */ +backend.add(eventsModuleCustomExtensions()); ``` This also requires that you have a dependency on the corresponding node package, @@ -373,12 +394,13 @@ implementations that they represent, and being exported from there. A basic installation of the scaffolder plugin looks as follows. -```diff - // packages/backend/src/index.ts -+import { scaffolderPlugin } from '@backstage/plugin-scaffolder-backend'; +```ts title="packages/backend/src/index.ts" +/* highlight-add-next-line */ +import { scaffolderPlugin } from '@backstage/plugin-scaffolder-backend'; - const backend = createBackend(); -+backend.add(scaffolderPlugin()); +const backend = createBackend(); +/* highlight-add-next-line */ +backend.add(scaffolderPlugin()); ``` If you have other customizations made to `plugins/scaffolder.ts`, such as adding @@ -390,32 +412,36 @@ mechanism to extend or tweak the functionality of the plugin. To do that, you'll make your own bespoke [module](../architecture/06-modules.md) which depends on the appropriate extension point and interacts with it. -```diff - // packages/backend/src/index.ts -+import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node'; -+import { createBackendModule } from '@backstage/backend-plugin-api'; +```ts title="packages/backend/src/index.ts" +/* highlight-add-start */ +import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node'; +import { createBackendModule } from '@backstage/backend-plugin-api'; +/* highlight-add-end */ -+const scaffolderModuleCustomExtensions = createBackendModule({ -+ pluginId: 'scaffolder', // name of the plugin that the module is targeting -+ moduleId: 'customExtensions', -+ register(env) { -+ env.registerInit({ -+ deps: { -+ scaffolder: scaffolderActionsExtensionPoint, -+ // ... and other dependencies as needed -+ }, -+ init({ scaffolder /* ..., other dependencies */ }) { -+ // Here you have the opportunity to interact with the extension -+ // point before the plugin itself gets instantiated -+ scaffolder.addActions(new MyAction()); // just an example -+ }, -+ }); -+ }, -+}); +/* highlight-add-start */ +const scaffolderModuleCustomExtensions = createBackendModule({ + pluginId: 'scaffolder', // name of the plugin that the module is targeting + moduleId: 'customExtensions', + register(env) { + env.registerInit({ + deps: { + scaffolder: scaffolderActionsExtensionPoint, + // ... and other dependencies as needed + }, + init({ scaffolder /* ..., other dependencies */ }) { + // Here you have the opportunity to interact with the extension + // point before the plugin itself gets instantiated + scaffolder.addActions(new MyAction()); // just an example + }, + }); + }, +}); +/* highlight-add-end */ - const backend = createBackend(); - backend.add(scaffolderPlugin()); -+backend.add(scaffolderModuleCustomExtensions()); +const backend = createBackend(); +backend.add(scaffolderPlugin()); +/* highlight-add-next-line */ +backend.add(scaffolderModuleCustomExtensions()); ``` This also requires that you have a dependency on the corresponding node package, diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index 616991123d..abc42ddbe0 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -23,8 +23,8 @@ yarn add --cwd packages/app @backstage/plugin-kubernetes Once the package has been installed, you need to import the plugin in your app by adding the "Kubernetes" tab to the respective catalog pages. -```tsx -// In packages/app/src/components/catalog/EntityPage.tsx +```tsx title="packages/app/src/components/catalog/EntityPage.tsx" +/* highlight-add-next-line */ import { EntityKubernetesContent } from '@backstage/plugin-kubernetes'; // You can add the tab to any number of pages, the service page is shown as an @@ -32,9 +32,13 @@ import { EntityKubernetesContent } from '@backstage/plugin-kubernetes'; const serviceEntityPage = ( {/* other tabs... */} + {/* highlight-add-start */} + {/* highlight-add-end */} + +) ``` **Notes:** @@ -57,8 +61,7 @@ yarn add --cwd packages/backend @backstage/plugin-kubernetes-backend Create a file called `kubernetes.ts` inside `packages/backend/src/plugins/` and add the following: -```typescript -// In packages/backend/src/plugins/kubernetes.ts +```ts title="packages/backend/src/plugins/kubernetes.ts" import { KubernetesBuilder } from '@backstage/plugin-kubernetes-backend'; import { Router } from 'express'; import { PluginEnvironment } from '../types'; @@ -81,14 +84,17 @@ And import the plugin to `packages/backend/src/index.ts`. There are three lines of code you'll need to add, and they should be added near similar code in your existing Backstage backend. -```typescript -// In packages/backend/src/index.ts +```typescript title="packages/backend/src/index.ts" +// .. +/* highlight-add-next-line */ import kubernetes from './plugins/kubernetes'; -// ... + async function main() { // ... + /* highlight-add-next-line */ const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes')); // ... + /* highlight-add-next-line */ apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv)); ``` @@ -104,52 +110,66 @@ don't work for your use-case, it is possible to implement a custom Change the following in `packages/backend/src/plugins/kubernetes.ts`: -```diff --import { KubernetesBuilder } from '@backstage/plugin-kubernetes-backend'; -+import { -+ ClusterDetails, -+ KubernetesBuilder, -+ KubernetesClustersSupplier, -+} from '@backstage/plugin-kubernetes-backend'; - import { Router } from 'express'; - import { PluginEnvironment } from '../types'; -+import { Duration } from 'luxon'; -+ -+export class CustomClustersSupplier implements KubernetesClustersSupplier { -+ constructor(private clusterDetails: ClusterDetails[] = []) {} -+ -+ static create(refreshInterval: Duration) { -+ const clusterSupplier = new CustomClustersSupplier(); -+ // setup refresh, e.g. using a copy of https://github.com/backstage/backstage/blob/master/plugins/search-backend-node/src/runPeriodically.ts -+ runPeriodically( -+ () => clusterSupplier.refreshClusters(), -+ refreshInterval.toMillis(), -+ ); -+ return clusterSupplier; -+ } -+ -+ async refreshClusters(): Promise { -+ this.clusterDetails = []; // fetch from somewhere -+ } -+ -+ async getClusters(): Promise { -+ return this.clusterDetails; -+ } -+} +```ts title="packages/backend/src/plugins/kubernetes.ts" +import { + /* highlight-add-next-line */ + ClusterDetails, + KubernetesBuilder, + /* highlight-add-next-line */ + KubernetesClustersSupplier, +} from '@backstage/plugin-kubernetes-backend'; +import { Router } from 'express'; +import { PluginEnvironment } from '../types'; +/* highlight-add-next-line */ +import { Duration } from 'luxon'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { -- const { router } = await KubernetesBuilder.createBuilder({ -+ const builder = await KubernetesBuilder.createBuilder({ +/* highlight-add-start */ +export class CustomClustersSupplier implements KubernetesClustersSupplier { + constructor(private clusterDetails: ClusterDetails[] = []) {} + + static create(refreshInterval: Duration) { + const clusterSupplier = new CustomClustersSupplier(); + // setup refresh, e.g. using a copy of https://github.com/backstage/backstage/blob/master/plugins/search-backend-node/src/runPeriodically.ts + runPeriodically( + () => clusterSupplier.refreshClusters(), + refreshInterval.toMillis(), + ); + return clusterSupplier; + } + + async refreshClusters(): Promise { + this.clusterDetails = []; // fetch from somewhere + } + + async getClusters(): Promise { + return this.clusterDetails; + } +} +/* highlight-add-end */ + +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + + /* highlight-remove-next-line */ + const { router } = await KubernetesBuilder.createBuilder({ + /* highlight-add-next-line */ + const builder = await KubernetesBuilder.createBuilder({ logger: env.logger, config: env.config, -- }).build(); -+ }); -+ builder.setClusterSupplier( -+ CustomClustersSupplier.create(Duration.fromObject({ minutes: 60 })), -+ ); -+ const { router } = await builder.build(); + /* highlight-remove-next-line */ + }).build(); + /* highlight-add-start */ + }); + builder.setClusterSupplier( + CustomClustersSupplier.create(Duration.fromObject({ minutes: 60 })), + ); + const { router } = await builder.build(); + /* highlight-add-end */ + + // .. + return router; +} ``` ## Running Backstage locally diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md index b464168724..7a00d10ede 100644 --- a/docs/features/search/how-to-guides.md +++ b/docs/features/search/how-to-guides.md @@ -20,30 +20,30 @@ to do that in two steps. [interface](https://github.com/backstage/backstage/blob/db2666b980853c281b8fe77905d7639c5d255f13/plugins/search/src/apis.ts#L31) according to your needs. -```typescript -export class SearchClient implements SearchApi { - // your implementation -} -``` + ```typescript + export class SearchClient implements SearchApi { + // your implementation + } + ``` 2. Override the API ref `searchApiRef` with your new implemented API in the `App.tsx` using `ApiFactories`. [Read more about App APIs](https://backstage.io/docs/api/utility-apis#app-apis). -```typescript -const app = createApp({ - apis: [ - // SearchApi - createApiFactory({ - api: searchApiRef, - deps: { discovery: discoveryApiRef }, - factory({ discovery }) { - return new SearchClient({ discoveryApi: discovery }); - }, - }), - ], -}); -``` + ```typescript + const app = createApp({ + apis: [ + // SearchApi + createApiFactory({ + api: searchApiRef, + deps: { discovery: discoveryApiRef }, + factory({ discovery }) { + return new SearchClient({ discoveryApi: discovery }); + }, + }), + ], + }); + ``` ## How to index TechDocs documents @@ -63,35 +63,35 @@ getting started guide. 1. Import the `DefaultTechDocsCollatorFactory` from `@backstage/plugin-techdocs-backend`. -```typescript -import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-techdocs-backend'; -``` + ```typescript + import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-techdocs-backend'; + ``` 2. If there isn't an existing schedule you'd like to run the collator on, be sure to create it first. Something like... -```typescript -import { Duration } from 'luxon'; + ```typescript + import { Duration } from 'luxon'; -const every10MinutesSchedule = env.scheduler.createScheduledTaskRunner({ - frequency: Duration.fromObject({ seconds: 600 }), - timeout: Duration.fromObject({ seconds: 900 }), - initialDelay: Duration.fromObject({ seconds: 3 }), -}); -``` + const every10MinutesSchedule = env.scheduler.createScheduledTaskRunner({ + frequency: Duration.fromObject({ seconds: 600 }), + timeout: Duration.fromObject({ seconds: 900 }), + initialDelay: Duration.fromObject({ seconds: 3 }), + }); + ``` 3. Register the `DefaultTechDocsCollatorFactory` with the IndexBuilder. -```typescript -indexBuilder.addCollator({ - schedule: every10MinutesSchedule, - factory: DefaultTechDocsCollatorFactory.fromConfig(env.config, { - discovery: env.discovery, - logger: env.logger, - tokenManager: env.tokenManager, - }), -}); -``` + ```typescript + indexBuilder.addCollator({ + schedule: every10MinutesSchedule, + factory: DefaultTechDocsCollatorFactory.fromConfig(env.config, { + discovery: env.discovery, + logger: env.logger, + tokenManager: env.tokenManager, + }), + }); + ``` You should now have your TechDocs documents indexed to your search engine of choice! @@ -101,14 +101,14 @@ searching, you can update your `SearchPage.tsx` file in `packages/app/src/components/search` by adding `techdocs` to the list of values of the `SearchType` component. -```tsx +```tsx title="packages/app/src/components/search/SearchPage.tsx" - ... + {/* ... */} ``` @@ -124,9 +124,7 @@ You can either just simply amend default behaviour, or even to write completely > `authorization` and `location` cannot be modified via a `entityTransformer`, `location` can be modified only through `locationTemplate`. -```diff -// packages/backend/src/plugins/search.ts - +```ts title="packages/backend/src/plugins/search.ts" const entityTransformer: CatalogCollatorEntityTransformer = (entity: Entity) => { if (entity.kind === 'SomeKind') { return { @@ -145,7 +143,8 @@ indexBuilder.addCollator({ collator: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, -+ entityTransformer, + /* highlight-add-next-line */ + entityTransformer, }), }); ``` @@ -166,17 +165,17 @@ exactly what's available to search, (or a [Decorator](./concepts.md#decorators) to filter things out here and there), but the `DefaultCatalogCollator` that's provided by `@backstage/plugin-catalog-backend` offers some configuration too! -```diff -// packages/backend/src/plugins/search.ts - +```ts title="packages/backend/src/plugins/search.ts" indexBuilder.addCollator({ defaultRefreshIntervalSeconds: 600, collator: DefaultCatalogCollator.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, -+ filter: { -+ kind: ['API', 'Component', 'Domain', 'Group', 'System', 'User'], -+ }, + /* highlight-add-start */ + filter: { + kind: ['API', 'Component', 'Domain', 'Group', 'System', 'User'], + }, + /* highlight-add-end */ }), }); ``` @@ -194,7 +193,7 @@ to create an override with your preferred styling. For example, the following will result in highlighted terms to be bold & underlined: -```jsx +```tsx const highlightOverride = { BackstageHighlightedSearchResultText: { highlight: { @@ -207,10 +206,6 @@ const highlightOverride = { }; ``` -[obj-mode]: https://nodejs.org/dist/latest-v16.x/docs/api/stream.html#stream_object_mode -[read-stream]: https://nodejs.org/dist/latest-v16.x/docs/api/stream.html#readable-streams -[async-gen]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of#iterating_over_async_generators - ## How to render search results using extensions Extensions for search results let you customize components used to render search result items, It is possible to provide your own search result item extensions or use the ones provided by plugin packages: @@ -219,8 +214,7 @@ Extensions for search results let you customize components used to render search Using the example below, you can provide an extension to be used as a default result item: -```tsx -// plugins/your-plugin/src/plugin.ts +```tsx title="plugins/your-plugin/src/plugin.ts" import { createPlugin } from '@backstage/core-plugin-api'; import { createSearchResultListItemExtension } from '@backstage/plugin-search-react'; @@ -251,8 +245,7 @@ export const YourSearchResultListItemExtension: ( Additionally, you can define a predicate function that receives a result and returns whether your extension should be used to render it or not: -```tsx -// plugins/your-plugin/src/plugin.ts +```tsx title="plugins/your-plugin/src/plugin.ts" import { createPlugin } from '@backstage/core-plugin-api'; import { createSearchResultListItemExtension } from '@backstage/plugin-search-react'; @@ -271,8 +264,7 @@ export const YourSearchResultListItemExtension = plugin.provide( Remember to export your new extension: -```tsx -// plugins/your-plugin/src/index.ts +```tsx title="plugins/your-plugin/src/index.ts" export { YourSearchResultListItem } from './plugin.ts'; ``` @@ -282,8 +274,7 @@ For more details, see the [createSearchResultListItemExtension](https://backstag Now that you know how a search result item is provided, let's finally see how they can be used, for example, to compose a page in your application: -```tsx -// packages/app/src/components/searchPage.tsx +```tsx title="packages/app/src/components/searchPage.tsx" import React from 'react'; import { Grid, Paper } from '@material-ui/core'; @@ -337,8 +328,7 @@ export const searchPage = ; As another example, here's a search modal that renders results with extensions: -```tsx -// packages/app/src/components/searchModal.tsx +```tsx title="packages/app/src/components/searchModal.tsx" import React from 'react'; import { DialogContent, DialogTitle, Paper } from '@material-ui/core'; @@ -367,7 +357,7 @@ export const SearchModal = ({ toggleModal }: { toggleModal: () => void }) => ( } /> } /> } /> - {/* As a "default" extension, it does not define a predicate function, + {/* As a "default" extension, it does not define a predicate function, so it must be the last child to render results that do not match the above extensions */} diff --git a/docs/features/software-catalog/catalog-customization.md b/docs/features/software-catalog/catalog-customization.md index 1b5535a464..c2ffa0c22a 100644 --- a/docs/features/software-catalog/catalog-customization.md +++ b/docs/features/software-catalog/catalog-customization.md @@ -142,21 +142,22 @@ export const EntitySecurityTierPicker = () => { Now we can add the component to `CustomCatalogPage`: -```diff +```tsx export const CustomCatalogPage = ({ columns, actions, initiallySelectedFilter = 'owned', }: CatalogPageProps) => { return ( - ... + {/* ... */} - ... + {/* ... */} }; ``` Finally, we can apply our new `CustomCatalogPage`. -```diff -# packages/app/src/App.tsx +```tsx title="packages/app/src/App.tsx" const routes = ( -- } /> -+ }> -+ -+ + {/* highlight-remove-next-line */} + } /> + {/* highlight-add-start */} + }> + + + {/* highlight-add-end */} + {/* ... */} + +); ``` The same method can be used to customize the _default_ filters with a different diff --git a/docs/features/software-catalog/extending-the-model.md b/docs/features/software-catalog/extending-the-model.md index 31c0ed90db..bdd043b8a8 100644 --- a/docs/features/software-catalog/extending-the-model.md +++ b/docs/features/software-catalog/extending-the-model.md @@ -530,12 +530,17 @@ export class FoobarEntitiesProcessor implements CatalogProcessor { Once the processor is created it can be wired up to the catalog via the `CatalogBuilder` in `packages/backend/src/plugins/catalog.ts`: -```diff -+ import { FoobarEntitiesProcessor } from '@internal/plugin-foobar-backend'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { FoobarEntitiesProcessor } from '@internal/plugin-foobar-backend'; - // ... - - const builder = await CatalogBuilder.create(env); -+ builder.addProcessor(new FoobarEntitiesProcessor()); - const { processingEngine, router } = await builder.build(); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-next-line */ + builder.addProcessor(new FoobarEntitiesProcessor()); + const { processingEngine, router } = await builder.build(); + // .. +} ``` diff --git a/docs/features/software-catalog/external-integrations.md b/docs/features/software-catalog/external-integrations.md index 5fc2537712..d8e4c2099a 100644 --- a/docs/features/software-catalog/external-integrations.md +++ b/docs/features/software-catalog/external-integrations.md @@ -235,26 +235,33 @@ others. You should now be able to add this class to your backend in `packages/backend/src/plugins/catalog.ts`: -```diff -+import { FrobsProvider } from '../path/to/class'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { FrobsProvider } from '../path/to/class'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = CatalogBuilder.create(env); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = CatalogBuilder.create(env); + /* highlight-add-start */ + const frobs = new FrobsProvider('production', env.reader); + builder.addEntityProvider(frobs); + /* highlight-add-end */ -+ const frobs = new FrobsProvider('production', env.reader); -+ builder.addEntityProvider(frobs); + const { processingEngine, router } = await builder.build(); + await processingEngine.start(); - const { processingEngine, router } = await builder.build(); - await processingEngine.start(); + /* highlight-add-start */ + await env.scheduler.scheduleTask({ + id: 'run_frobs_refresh', + fn: async () => { await frobs.run(); }, + frequency: { minutes: 30 }, + timeout: { minutes: 10 }, + }); + /* highlight-add-end */ -+ await env.scheduler.scheduleTask({ -+ id: 'run_frobs_refresh', -+ fn: async () => { await frobs.run(); }, -+ frequency: { minutes: 30 }, -+ timeout: { minutes: 10 }, -+ }); + // .. +} ``` Note that we used the builtin scheduler facility to regularly call the `run` @@ -464,8 +471,7 @@ feeding it into the ingestion loop. For this kind of an integration, you'd typically want to add it to the list of statically always-available locations in the config. -```yaml -# In app-config.yaml +```yaml title="app-config.yaml" catalog: locations: - type: system-x @@ -551,14 +557,19 @@ The key points to note are: You should now be able to add this class to your backend in `packages/backend/src/plugins/catalog.ts`: -```diff -+import { SystemXReaderProcessor } from '../path/to/class'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { SystemXReaderProcessor } from '../path/to/class'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = CatalogBuilder.create(env); -+ builder.addProcessor(new SystemXReaderProcessor(env.reader)); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = CatalogBuilder.create(env); + /* highlight-add-next-line */ + builder.addProcessor(new SystemXReaderProcessor(env.reader)); + + // .. +} ``` Start up the backend - it should now start reading from the previously diff --git a/docs/features/software-templates/builtin-actions.md b/docs/features/software-templates/builtin-actions.md index c8f830f3ee..1b3a53b5d9 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -31,16 +31,19 @@ allow most templates built for `fetch:cookiecutter` to work without any changes. 2. Set `cookiecutterCompat` to `true` in the `fetch:template` step input in `template.yaml`. -```diff - steps: - - id: fetch-base - name: Fetch Base -- action: fetch:cookiecutter -+ action: fetch:template - input: - url: ./skeleton -+ cookiecutterCompat: true - values: +```yaml title="template.yaml" +steps: + - id: fetch-base + name: Fetch Base + # highlight-remove-next-line + action: fetch:cookiecutter + # highlight-add-next-line + action: fetch:template + input: + url: ./skeleton + # highlight-add-next-line + cookiecutterCompat: true + values: ``` ### Manual migration diff --git a/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md b/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md index f9d2c4eb0c..bd8d4bdb72 100644 --- a/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md +++ b/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md @@ -38,14 +38,20 @@ to upgrade. An important change is to add the required processor to your `packages/backend/src/plugins/catalog.ts` -```diff -+import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend'; -... +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-next-line */ + builder.addProcessor(new ScaffolderEntitiesProcessor()); + const { processingEngine, router } = await builder.build(); - const builder = await CatalogBuilder.create(env); -+ builder.addProcessor(new ScaffolderEntitiesProcessor()); - const { processingEngine, router } = await builder.build(); + // .. +} ``` ## `backstage.io/v1beta2` -> `scaffolder.backstage.io/v1beta3` @@ -53,10 +59,12 @@ An important change is to add the required processor to your `packages/backend/s The most important change is that you'll need to switch over the `apiVersion` in your templates to the new one. -```diff +```yaml kind: Template -- apiVersion: backstage.io/v1beta2 -+ apiVersion: scaffolder.backstage.io/v1beta3 + # highlight-remove-next-line + apiVersion: backstage.io/v1beta2 + # highlight-add-next-line + apiVersion: scaffolder.backstage.io/v1beta3 ``` ## `${{ }}` instead of `"{{ }}"` @@ -68,15 +76,19 @@ was pretty annoying, as it also meant that all things look like strings. Now that's no longer the case, you can now remove the `""` and take advantage of writing nice `yaml` files that just work. -```diff - spec: - steps: - input: - allowedHosts: ['github.com'] -- description: 'This is {{ parameters.name }}' -+ description: This is ${{ parameters.name }} -- repoUrl: '{{ parameters.repoUrl }}' -+ repoUrl: ${{ parameters.repoUrl }} +```yaml +spec: + steps: + input: + allowedHosts: ['github.com'] + # highlight-remove-next-line + description: 'This is {{ parameters.name }}' + # highlight-add-next-line + description: This is ${{ parameters.name }} + # highlight-remove-next-line + repoUrl: '{{ parameters.repoUrl }}' + # highlight-add-next-line + repoUrl: ${{ parameters.repoUrl }} ``` ## No more `eq` or `not` helpers @@ -85,24 +97,26 @@ These helpers are no longer needed with the more expressive `api` that `nunjucks` provides. You can simply use the built-in `nunjucks` and `jinja2` style operators. -```diff - spec: - steps: - input: -- if: '{{ eq parameters.value "backstage" }}' -+ if: ${{ parameters.value === "backstage" }} - ... +```yaml +spec: + steps: + input: + # highlight-remove-next-line + if: '{{ eq parameters.value "backstage" }}' + # highlight-add-next-line + if: ${{ parameters.value === "backstage" }} ``` And then for the `not` -```diff - spec: - steps: - input: -- if: '{{ not parameters.value "backstage" }}' -+ if: ${{ parameters.value !== "backstage" }} - ... +```yaml +spec: + steps: + input: + # highlight-remove-next-line + if: '{{ not parameters.value "backstage" }}' + # highlight-add-next-line + if: ${{ parameters.value !== "backstage" }} ``` Much better right? ✨ @@ -115,32 +129,36 @@ supporting the additional primitive values now rather than everything being a should all work as expected and keep the type that has been declared in the input schema. -```diff - spec: - parameters: - test: - type: number - name: Test Number - address: - type: object - required: - - line1 - properties: - line1:🙏 - type: string - name: Line 1 - line2: - type: string - name: Line 2 +```yaml +spec: + parameters: + test: + type: number + name: Test Number + address: + type: object + required: + - line1 + properties: + line1: + type: string + name: Line 1 + line2: + type: string + name: Line 2 - steps: - - id: test step - action: run:something - input: -- address: '{{ json parameters.address }}' -+ address: ${{ parameters.address }} -- test: '{{ parameters.test }}' -+ test: ${{ parameters.test }} # this will now make sure that the type of test is a number 🙏 + steps: + - id: test step + action: run:something + input: + # highlight-remove-next-line + address: '{{ json parameters.address }}' + # highlight-add-next-line + address: ${{ parameters.address }} + # highlight-remove-next-line + test: '{{ parameters.test }}' + # highlight-add-next-line + test: ${{ parameters.test }} # this will now make sure that the type of test is a number 🙏 ``` ## `parseRepoUrl` is now a `filter` @@ -148,13 +166,14 @@ input schema. All calls to `parseRepoUrl` are now a `jinja2` `filter`, which means you'll need to update the syntax. -```diff - spec: - steps: - input: -- repoUrl: '{{ parseRepoUrl parameters.repoUrl }}' -+ repoUrl: ${{ parameters.repoUrl | parseRepoUrl }} - ... +```yaml +spec: + steps: + input: + # highlight-remove-next-line + repoUrl: '{{ parseRepoUrl parameters.repoUrl }}' + # highlight-add-next-line + repoUrl: ${{ parameters.repoUrl | parseRepoUrl }} ``` Now we have complex value support here too, expect that this `filter` will go @@ -167,39 +186,46 @@ away in future versions and the `RepoUrlPicker` will return an object so Previously, it was possible to provide links to the frontend using the named output `entityRef` and `remoteUrl`. These should be moved to `links` under the `output` object instead. -```diff - output: -- remoteUrl: {{ steps['publish'].output.remoteUrl }} -- entityRef: {{ steps['register'].output.entityRef }} -+ links: -+ - title: Repository -+ url: ${{ steps['publish'].output.remoteUrl }} -+ - title: Open in catalog -+ icon: catalog -+ entityRef: ${{ steps['register'].output.entityRef }} - +```yaml +output: + # highlight-remove-start + remoteUrl: {{ steps['publish'].output.remoteUrl }} + entityRef: {{ steps['register'].output.entityRef }} + # highlight-remove-end + # highlight-add-start + links: + - title: Repository + url: ${{ steps['publish'].output.remoteUrl }} + - title: Open in catalog + icon: catalog + entityRef: ${{ steps['register'].output.entityRef }} + # highlight-add-end ``` ## Watch out for `dash-case` The nunjucks compiler can run into issues if the `id` fields in your template steps use dash characters, since these IDs translate directly to JavaScript object properties when accessed as output. One possible migration path is to use `camelCase` for your action IDs. -```diff +```yaml steps: -- id: my-custom-action -- ... -- -- id: publish-pull-request -- input: -- repoUrl: {{ steps.my-custom-action.output.repoUrl }} # Will not recognize 'my-custom-action' as a JS property since it contains dashes! + # highlight-remove-start + id: my-custom-action + ... + + id: publish-pull-request + input: + repoUrl: {{ steps.my-custom-action.output.repoUrl }} # Will not recognize 'my-custom-action' as a JS property since it contains dashes! + # highlight-remove-end steps: -+ id: myCustomAction -+ ... -+ -+ id: publishPullRequest -+ input: -+ repoUrl: ${{ steps.myCustomAction.output.repoUrl }} + # highlight-add-start + id: myCustomAction + ... + + id: publishPullRequest + input: + repoUrl: ${{ steps.myCustomAction.output.repoUrl }} + # highlight-add-end ``` Alternatively, it's possible to keep the `dash-case` syntax and use brackets for property access as you would in JavaScript: diff --git a/docs/features/software-templates/testing-scaffolder-alpha.md b/docs/features/software-templates/testing-scaffolder-alpha.md index 76479b137e..df89e0f1b1 100644 --- a/docs/features/software-templates/testing-scaffolder-alpha.md +++ b/docs/features/software-templates/testing-scaffolder-alpha.md @@ -41,39 +41,43 @@ It's also worth calling out that if you do test this out, and find some issues o The `ScaffolderPage` router has a completely different export for the `scaffolder/next` work, so you will want to change any import from the old `ScaffolderPage` to the new `NextScaffolderPage` -```diff -- import { ScaffolderPage } from '@backstage/plugin-scaffolder'; -+ import { NextScaffolderPage } from '@backstage/plugin-scaffolder/alpha'; +```tsx +/* highlight-remove-next-line */ +import { ScaffolderPage } from '@backstage/plugin-scaffolder'; +/* highlight-add-next-line */ +import { NextScaffolderPage } from '@backstage/plugin-scaffolder/alpha'; ``` And this API should be the exact same as the previous Router, so you should be able to make a change like the following further down in this file: -```diff - - entity?.metadata?.tags?.includes('recommended') ?? false, - }, - ]} - /> - } - > - - - ... other extensions - - - - ... other layouts - - +```tsx + + entity?.metadata?.tags?.includes('recommended') ?? false, + }, + ]} + /> + } + > + + + {/* ... other extensions */} + + + + {/* ... other layouts */} + + ``` ### Make the required changes to your `CustomFieldExtensions` @@ -95,13 +99,17 @@ export const EntityNamePickerFieldExtension = scaffolderPlugin.provide( References for `createScaffolderFieldExtension` have an `/alpha` version of `createNextScaffolderFieldExtension`, which should be used instead. -```diff --import { createScaffolderFieldExtension } from '@backstage/plugin-scaffolder'; -+import { createNextScaffolderFieldExtension } from '@backstage/plugin-scaffolder/alpha'; +```ts +/* highlight-remove-next-line */ +import { createScaffolderFieldExtension } from '@backstage/plugin-scaffolder'; +/* highlight-add-next-line */ +import { createNextScaffolderFieldExtension } from '@backstage/plugin-scaffolder/alpha'; export const EntityNamePickerFieldExtension = scaffolderPlugin.provide( -- createScaffolderFieldExtension({ -+ createNextScaffolderFieldExtension({ + /* highlight-remove-next-line */ + createScaffolderFieldExtension({ + /* highlight-add-next-line */ + createNextScaffolderFieldExtension({ component: EntityNamePicker, name: 'EntityNamePicker', validation: entityNamePickerValidation, @@ -113,7 +121,7 @@ Once you've done this you will find that you will have two squiggly lines under Let's take the following code for the `EntityNamePicker` component: -```ts +```tsx export const EntityNamePicker = ( props: FieldExtensionComponentProps, ) => { @@ -127,19 +135,23 @@ export const EntityNamePicker = ( idSchema, placeholder, } = props; - ... + // .. } ``` There's another `/alpha` export that you need to replace `FieldExtensionComponentProps` with which is the `NextFieldExtensionComponentProps`. -```diff -- import { FieldExtensionComponentProps } from '@backstage/plugin-scaffolder-react'; -+ import { NextFieldExtensionComponentProps } from '@backstage/plugin-scaffolder-react/alpha'; +```tsx +/* highlight-remove-next-line */ +import { FieldExtensionComponentProps } from '@backstage/plugin-scaffolder-react'; +/* highlight-add-next-line */ +import { NextFieldExtensionComponentProps } from '@backstage/plugin-scaffolder-react/alpha'; export const EntityNamePicker = ( -- props: FieldExtensionComponentProps, -+ props: NextFieldExtensionComponentProps, + /* highlight-remove-next-line */ + props: FieldExtensionComponentProps, + /* highlight-add-next-line */ + props: NextFieldExtensionComponentProps, ) => { const { onChange, @@ -147,12 +159,14 @@ export const EntityNamePicker = ( schema: { title = 'Name', description = 'Unique name of the component' }, rawErrors, formData, -- uiSchema: { 'ui:autofocus': autoFocus }, -+ uiSchema: { 'ui:autofocus': autoFocus } = {}, + /* highlight-remove-next-line */ + uiSchema: { 'ui:autofocus': autoFocus }, + /* highlight-add-next-line */ + uiSchema: { 'ui:autofocus': autoFocus } = {}, idSchema, placeholder, } = props; - ... + // .. } ``` @@ -182,8 +196,10 @@ You will need to change the import for `FieldValidation` to point at the new `re > Note: you will probably need to install this dependency too, by using `yarn add @rjsf/utils` in the package where you define these validation functions, this could also be in the `packages/app` folder, so you can install it there if needed. -```diff +```ts +/* highlight-remove-next-line */ - import { FieldValidation } from '@rjsf/core'; +/* highlight-add-next-line */ + import { FieldValidation } from '@rjsf/utils; import { KubernetesValidatorFunctions } from '@backstage/catalog-model'; @@ -201,34 +217,40 @@ Once we fully release the code that is in the `/alpha` exports right now onto th Later releases of `react-jsonschema-form` have made the `uiSchema` optional, and if you don't provide it, it will be `undefined` instead of an empty object. This means that you will need to make sure that you're defaulting the `uiSchema` to an empty object if you're using it in your code. -```diff +```tsx const { onChange, required, schema: { title = 'Name', description = 'Unique name of the component' }, rawErrors, formData, -- uiSchema: { 'ui:autofocus': autoFocus }, -+ uiSchema: { 'ui:autofocus': autoFocus } = {}, + /* highlight-remove-next-line */ + uiSchema: { 'ui:autofocus': autoFocus }, + /* highlight-add-next-line */ + uiSchema: { 'ui:autofocus': autoFocus } = {}, idSchema, placeholder, } = props; + // .. ``` ### `formData` can also be `undefined` If you were using the `formData` and assuming that it was set to an empty object when building `Field Extensions` that return objects, then this will be `undefined` now due to a change in the `react-jsonschema-form` library. -```diff +```tsx const { onChange, required, schema: { title = 'Name', description = 'Unique name of the component' }, rawErrors, -- formData, -+ formData = {}, // or maybe some other default value that you would prefer + /* highlight-remove-next-line */ + formData, + /* highlight-add-next-line */ + formData = {}, // or maybe some other default value that you would prefer uiSchema: { 'ui:autofocus': autoFocus } = {}, idSchema, placeholder, } = props; + // .. ``` diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 3f7edd23a0..090539a6b1 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -31,18 +31,16 @@ Once the package has been installed, you need to import the plugin in your app. In `packages/app/src/App.tsx`, import `TechDocsPage` and add the following to `FlatRoutes`: -```tsx +```tsx title="packages/app/src/App.tsx" import { DefaultTechDocsHome, TechDocsIndexPage, TechDocsReaderPage, } from '@backstage/plugin-techdocs'; -// ... - const AppRoutes = () => { - // ... other plugin routes + {/* ... other plugin routes */} }> @@ -58,20 +56,20 @@ It would be nice to decorate your pages with something else... Having a link tha With the [TechDocs Addon framework](https://backstage.io/docs/features/techdocs/addons#installing-and-using-addons), you can render React components in documentation pages and these Addons can be provided by any Backstage plugin. The framework is exported by the [@backstage/plugin-techdocs-react](https://www.npmjs.com/package/@backstage/plugin-techdocs-react) package and there is a `` Addon in the [@backstage/plugin-techdocs-module-addons-contrib](https://www.npmjs.com/package/@backstage/plugin-techdocs-module-addons-contrib) package for you to use once you have these two dependencies installed: -```diff +```tsx import { DefaultTechDocsHome, TechDocsIndexPage, TechDocsReaderPage, } from '@backstage/plugin-techdocs'; -+ import { TechDocsAddons } from '@backstage/plugin-techdocs-react'; -+ import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib'; - -// ... +/* highlight-add-start */ +import { TechDocsAddons } from '@backstage/plugin-techdocs-react'; +import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib'; +/* highlight-add-end */ const AppRoutes = () => { - // ... other plugin routes + {/* ... other plugin routes */} }> @@ -79,9 +77,11 @@ const AppRoutes = () => { path="/docs/:namespace/:kind/:name/*" element={} > -+ -+ -+ + {/* highlight-add-start */} + + + + {/* highlight-add-end */} ; }; diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md index 5ec0d6eeab..fcb27c220d 100644 --- a/docs/getting-started/app-custom-theme.md +++ b/docs/getting-started/app-custom-theme.md @@ -172,7 +172,7 @@ When creating a custom theme you would be applying different values to component's css rules that use the theme object. For example, a Backstage component's styles might look like this: -```ts +```tsx const useStyles = makeStyles( theme => ({ header: { @@ -263,11 +263,9 @@ You can also use another web image format such as PNG by importing it. To do this, place your new image into a new subdirectory such as `src/components/Root/logo/my-company-logo.png`, and then add this code: -```jsx +```tsx import MyCustomLogoFull from './logo/my-company-logo.png'; -//... - const LogoFull = () => { return ; }; @@ -294,8 +292,7 @@ In your front-end application, locate the `src` folder. We suggest creating the > Another example [here](https://github.com/backstage/backstage/blob/master/plugins/azure-devops/src/components/AzurePipelinesIcon/AzurePipelinesIcon.tsx), if you want to ensure proper behavior in light and dark themes. -```tsx -// customIcons.tsx +```tsx title="customIcons.tsx" import { SvgIcon, SvgIconProps } from '@material-ui/core'; import React from 'react'; @@ -317,29 +314,28 @@ export const ExampleIcon = (props: SvgIconProps) => ( Supply your custom icon in `packages/app/src/App.tsx` -```diff +```tsx title="packages/app/src/App.tsx" +/* highlight-add-next-line */ +import { ExampleIcon } from './assets/customIcons' -+ import { ExampleIcon } from './assets/customIcons' - -[...] const app = createApp({ apis, components: { - [...] + {/* ... */} }, themes: [ - [...] + {/* ... */} ], -+ icons: { -+ github: ExampleIcon, -+ }, + /* highlight-add-start */ + icons: { + github: ExampleIcon, + }, + /* highlight-add-end */ bindRoutes({ bind }) { - [...] + {/* ... */} } }) - -[...] ``` ### Adding Icons @@ -350,17 +346,19 @@ You can add more icons, if the [default icons](https://github.com/backstage/back 2. Then you want to import your icon, add this to the rest of your imports: `import AlarmIcon from '@material-ui/icons/Alarm';` 3. Next you want to add the icon like this to your `createApp`: - ```diff - const app = createApp({ - apis: ..., - plugins: ..., - + icons: { - + alert: AlarmIcon, - + }, - themes: ..., - components: ..., - }); - ``` + ```tsx title="packages/app/src/App.tsx" + const app = createApp({ + apis: ..., + plugins: ..., + /* highlight-add-start */ + icons: { + alert: AlarmIcon, + }, + /* highlight-add-end */ + themes: ..., + components: ..., + }); + ``` 4. Now we can reference `alert` for our icon in our entity links like this: @@ -404,7 +402,7 @@ For this example we'll show you how you can expand the sidebar with a sub-menu: 1. Open the `Root.tsx` file located in `packages/app/src/components/Root` as this is where the sidebar code lives 2. Then we want to add the following imports for the icons: - ```ts + ```tsx title="packages/app/src/components/Root/Root.tsx" import ApiIcon from '@material-ui/icons/Extension'; import ComponentIcon from '@material-ui/icons/Memory'; import DomainIcon from '@material-ui/icons/Apartment'; @@ -415,69 +413,71 @@ For this example we'll show you how you can expand the sidebar with a sub-menu: 3. Then update the `@backstage/core-components` import like this: - ```diff - import { - Sidebar, - sidebarConfig, - SidebarDivider, - SidebarGroup, - SidebarItem, - SidebarPage, - SidebarScrollWrapper, - SidebarSpace, - useSidebarOpenState, - Link, - + GroupIcon, - + SidebarSubmenu, - + SidebarSubmenuItem, - } from '@backstage/core-components'; - ``` + ```tsx + import { + Sidebar, + sidebarConfig, + SidebarDivider, + SidebarGroup, + SidebarItem, + SidebarPage, + SidebarScrollWrapper, + SidebarSpace, + useSidebarOpenState, + Link, + /* highlight-add-start */ + GroupIcon, + SidebarSubmenu, + SidebarSubmenuItem, + /* highlight-add-end */ + } from '@backstage/core-components'; + ``` 4. Finally replace `` with this: - ```ts - - - - - - - - - - - - - - ``` + ```tsx + + + + + + + + + + + + + + ``` When you startup your Backstage app and hover over the Home option on the sidebar you'll now see a nice sub-menu appear with links to the various Kinds in your Catalog. It would look like this: diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index a436321fe2..2196a1a36d 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -74,22 +74,26 @@ Use your favorite editor to open `app-config.yaml` and add your PostgreSQL configuration. in the root directory of your Backstage app using the credentials from the previous steps. -```diff +```yaml title="app-config.yaml" backend: database: -- client: better-sqlite3 -- connection: ':memory:' -+ # config options: https://node-postgres.com/apis/client -+ client: pg -+ connection: -+ host: ${POSTGRES_HOST} -+ port: ${POSTGRES_PORT} -+ user: ${POSTGRES_USER} -+ password: ${POSTGRES_PASSWORD} -+ # https://node-postgres.com/features/ssl -+ #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) -+ #ca: # if you have a CA file and want to verify it you can uncomment this section -+ #$file: /ca/server.crt + # highlight-remove-start + client: better-sqlite3 + connection: ':memory:' + # highlight-remove-end + # highlight-add-start + # config options: https://node-postgres.com/apis/client + client: pg + connection: + host: ${POSTGRES_HOST} + port: ${POSTGRES_PORT} + user: ${POSTGRES_USER} + password: ${POSTGRES_PASSWORD} + # https://node-postgres.com/features/ssl + # ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) + #ca: # if you have a CA file and want to verify it you can uncomment this section + #$file: /ca/server.crt + # highlight-add-end ``` You'll use the connection details from the previous step. You can either set the @@ -142,7 +146,7 @@ Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`, and add your `clientId` and `clientSecret` to this file. It should end up looking like this: -```yaml +```yaml title="app-config.yaml" auth: # see https://backstage.io/docs/auth/ to learn about auth providers environment: development @@ -161,14 +165,14 @@ change the sign-in page, this you actually need to add in the source code. Open `packages/app/src/App.tsx` and below the last `import` line, add: -```typescript +```typescript title="packages/app/src/App.tsx" import { githubAuthApiRef } from '@backstage/core-plugin-api'; import { SignInPage } from '@backstage/core-components'; ``` Search for `const app = createApp({` in this file, and below `apis,` add: -```typescript +```tsx title="packages/app/src/App.tsx" components: { SignInPage: props => ( - ... - + - + - + ; - - ); - ``` + const cicdContent = ( + + {/* ... */} + {/* highlight-add-next-line */} + + + ; + {/* highlight-add-end */} + + ); + ``` This is just one example, but each Backstage instance may integrate content or cards to suit their needs on different pages, tabs, etc. In addition, while some @@ -62,8 +64,7 @@ to an entity in the software catalog. Plugins that collect data off of external services may require the use of a proxy service. This plugin accesses the CircleCI REST API, and thus requires a proxy definition. - ```yaml - // app-config.yaml + ```yaml title="app-config.yaml" proxy: '/circleci/api': target: https://circleci.com/api/v1.1 @@ -82,7 +83,7 @@ adding new `SidebarItem` elements. For example, if you install the `api-docs` plugin, a matching `SidebarItem` could be something like this: -```tsx +```tsx title="packages/app/src/components/Root/Root.tsx" // Import icon from MUI import ExtensionIcon from '@material-ui/icons/Extension'; @@ -95,7 +96,7 @@ are sized according to the Material UI's [SvgIcon](https://material-ui.com/api/svg-icon/) default of 24x24px, and set the extension to `.icon.svg`. For example: -```ts +```tsx import InternalToolIcon from './internal-tool.icon.svg'; ``` @@ -104,7 +105,7 @@ customizing the experience you can group `SidebarItems` in a `SidebarGroup` (Example 1) or create a `SidebarGroup` with a link (Example 2). All `SidebarGroup`s are displayed in the bottom navigation with an icon. -```ts +```tsx // Example 1 } label="Menu"> ... @@ -113,7 +114,7 @@ customizing the experience you can group `SidebarItems` in a `SidebarGroup` ``` -```ts +```tsx // Example 2 } to="/search"> ... diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index 9fa91e694f..29b427bad8 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -52,29 +52,34 @@ If you don't have a homepage already, most likely you have a redirect setup to u Inside your `packages/app/src/App.tsx`, look for -```tsx +```tsx title="packages/app/src/App.tsx" const routes = ( + {/* ... */} + +) ``` Let's replace the `` line and use the new component we created in the previous step as the new homepage. -```diff -// File: packages/app/src/App.tsx +```tsx title="packages/app/src/App.tsx" +/* highlight-add-start */ +import { HomepageCompositionRoot } from '@backstage/plugin-home'; +import { HomePage } from './components/home/HomePage'; +/* highlight-add-end */ -+ import { HomepageCompositionRoot } from '@backstage/plugin-home'; -+ import { HomePage } from './components/home/HomePage'; - -// ... const routes = ( -- -+ }> -+ -+ -// ... - + {/* highlight-remove-next-line */} + + {/* highlight-add-start */} + }> + + + {/* highlight-add-end */} + {/* ... */} + ) ``` @@ -90,26 +95,34 @@ The code for the Backstage sidebar is most likely inside your [`packages/app/src Let's make the following changes -```diff -// Other imports -+ import CategoryIcon from '@material-ui/icons/Category'; +```tsx title="packages/app/src/components/Root/Root.tsx" +/* highlight-add-next-line */ +import CategoryIcon from '@material-ui/icons/Category'; export const Root = ({ children }: PropsWithChildren<{}>) => ( - # ... + {/* ... */} }> {/* Global nav, not org-specific */} -- -+ -+ + {/* highlight-remove-next-line */} + + {/* highlight-add-start */} + + + {/* highlight-add-end */} {/* End global nav */} + {/* ... */} + + + +) ``` That's it! You should now have _(although slightly boring)_ a homepage! diff --git a/docs/integrations/azure/discovery.md b/docs/integrations/azure/discovery.md index 6cb135900e..d4ded290c3 100644 --- a/docs/integrations/azure/discovery.md +++ b/docs/integrations/azure/discovery.md @@ -32,8 +32,7 @@ Setup [Azure integration](locations.md) with `host` and `token`. Host must be `d At your configuration, you add one or more provider configs: -```yaml -# app-config.yaml +```yaml title="app-config.yaml" catalog: providers: azureDevOps: @@ -94,39 +93,45 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-azure Once you've done that, you'll also need to add the segment below to `packages/backend/src/plugins/catalog.ts`: -```diff -/* packages/backend/src/plugins/catalog.ts */ -+import { AzureDevOpsEntityProvider } from '@backstage/plugin-catalog-backend-module-azure'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { AzureDevOpsEntityProvider } from '@backstage/plugin-catalog-backend-module-azure'; const builder = await CatalogBuilder.create(env); /** ... other processors and/or providers ... */ -+builder.addEntityProvider( -+ AzureDevOpsEntityProvider.fromConfig(env.config, { -+ logger: env.logger, -+ // optional: alternatively, use scheduler with schedule defined in app-config.yaml -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 30 }, -+ timeout: { minutes: 3 }, -+ }), -+ // optional: alternatively, use schedule -+ scheduler: env.scheduler, -+ }), -+); +/* highlight-add-start */ +builder.addEntityProvider( + AzureDevOpsEntityProvider.fromConfig(env.config, { + logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule + scheduler: env.scheduler, + }), +); +/* highlight-add-end */ ``` ## Alternative Processor As an alternative to the entity provider `AzureDevOpsEntityProvider`, you can still use the `AzureDevopsDiscoveryProcessor`. -```diff -// In packages/backend/src/plugins/catalog.ts -+import { AzureDevOpsDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-azure'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { AzureDevOpsDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-azure'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); -+ builder.addProcessor(AzureDevOpsDiscoveryProcessor.fromConfig(env.config, { logger: env.logger })); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-next-line */ + builder.addProcessor(AzureDevOpsDiscoveryProcessor.fromConfig(env.config, { logger: env.logger })); + + // .. +} ``` ```yaml diff --git a/docs/integrations/azure/org.md b/docs/integrations/azure/org.md index acb43db182..403f0042a9 100644 --- a/docs/integrations/azure/org.md +++ b/docs/integrations/azure/org.md @@ -21,7 +21,7 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-msgraph Next add the basic configuration to `app-config.yaml` -```yaml +```yaml title="app-config.yaml" catalog: providers: microsoftGraphOrg: @@ -39,25 +39,30 @@ catalog: Finally, register the plugin in `catalog.ts`. For large organizations, this plugin can take a long time, so be careful setting low frequency / timeouts. -```diff - // packages/backend/src/plugins/catalog.ts -+import { MicrosoftGraphOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-msgraph'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { MicrosoftGraphOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-msgraph'; - export default async function createPlugin( +export default async function createPlugin( env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); +): Promise { + const builder = await CatalogBuilder.create(env); -+ builder.addEntityProvider( -+ MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { -+ logger: env.logger, -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { hours: 1 }, -+ timeout: { minutes: 50 }, -+ initialDelay: { seconds: 15} -+ }), -+ }), -+ ); + /* highlight-add-start */ + builder.addEntityProvider( + MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { + logger: env.logger, + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { hours: 1 }, + timeout: { minutes: 50 }, + initialDelay: { seconds: 15} + }), + }), + ); + /* highlight-add-end */ + + // .. +} ``` ## Authenticating with Microsoft Graph @@ -71,7 +76,7 @@ If you can't do this, you'll have to create an App Registration. ### App Registration -If none of the other authentication methods work, you can create an app registration in the azure portal. +If none of the other authentication methods work, you can create an app registration in the azure portal. By default the graph plugin requires the following Application permissions (not Delegated) for Microsoft Graph: - `GroupMember.Read.All` @@ -150,15 +155,17 @@ Entities can also be excluded from backstage by returning `undefined`. These Transformers are be registered when configuring `MicrosoftGraphOrgEntityProvider` -```diff - builder.addEntityProvider( - MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { - // ... -+ groupTransformer: myGroupTransformer, -+ userTransformer: myUserTransformer, -+ organizationTransformer: myOrganizationTransformer, - }), - ); +```ts +builder.addEntityProvider( + MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { + // ... + /* highlight-add-start */ + groupTransformer: myGroupTransformer, + userTransformer: myUserTransformer, + organizationTransformer: myOrganizationTransformer, + /* highlight-add-end */ + }), +); ``` When using custom transformers, you may want to customize the data returned. @@ -243,7 +250,7 @@ Try importing a smaller set of data (e.g. `filter: displayName eq 'John Smith'`) See [Troubleshooting Azure Identity Authentication Issues](https://aka.ms/azsdk/js/identity/troubleshoot) -### Error while reading users from Microsoft Graph: Authorization_RequestDenied - Insufficient privileges to complete the operation. +### Error while reading users from Microsoft Graph: Authorization_RequestDenied - Insufficient privileges to complete the operation - Make sure you've granted all the required permissions to your application registration or managed identity - Make sure the permissions are `Application` permissions rather than `Delegated` diff --git a/docs/integrations/bitbucketCloud/discovery.md b/docs/integrations/bitbucketCloud/discovery.md index f6ceab9ff7..7074fcac1b 100644 --- a/docs/integrations/bitbucketCloud/discovery.md +++ b/docs/integrations/bitbucketCloud/discovery.md @@ -28,41 +28,46 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-bitbuck And then add the entity provider to your catalog builder: -```diff -// packages/backend/src/plugins/catalog.ts -+ import { BitbucketCloudEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-cloud'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { BitbucketCloudEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-cloud'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); -+ builder.addEntityProvider( -+ BitbucketCloudEntityProvider.fromConfig(env.config, { -+ logger: env.logger, -+ scheduler: env.scheduler, -+ }), -+ ); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-start */ + builder.addEntityProvider( + BitbucketCloudEntityProvider.fromConfig(env.config, { + logger: env.logger, + scheduler: env.scheduler, + }), + ); + /* highlight-add-end */ - // [...] - } + // .. +} ``` Alternatively to the config-based schedule, you can use -```diff -- scheduler: env.scheduler, -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 30 }, -+ timeout: { minutes: 3 }, -+ }), +```ts +/* highlight-remove-next-line */ +scheduler: env.scheduler, +/* highlight-add-start */ +schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, +}), +/* highlight-add-end */ ``` ### Installation with Events Support Please follow the installation instructions at -- https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md -- https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-bitbucket-cloud/README.md +- +- Additionally, you need to decide how you want to receive events from external sources like @@ -71,30 +76,35 @@ Additionally, you need to decide how you want to receive events from external so Set up your provider -```diff -// packages/backend/src/plugins/catalogEventBasedProviders.ts -+import { CatalogClient } from '@backstage/catalog-client'; -+import { BitbucketCloudEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-cloud'; - import { EntityProvider } from '@backstage/plugin-catalog-node'; - import { EventSubscriber } from '@backstage/plugin-events-node'; - import { PluginEnvironment } from '../types'; +```ts title="packages/backend/src/plugins/catalogEventBasedProviders.ts" +/* highlight-add-start */ +import { CatalogClient } from '@backstage/catalog-client'; +import { BitbucketCloudEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-cloud'; +/* highlight-add-end */ +import { EntityProvider } from '@backstage/plugin-catalog-node'; +import { EventSubscriber } from '@backstage/plugin-events-node'; +import { PluginEnvironment } from '../types'; - export default async function createCatalogEventBasedProviders( -- _: PluginEnvironment, -+ env: PluginEnvironment, - ): Promise> { - const providers: Array< - (EntityProvider & EventSubscriber) | Array - > = []; -- // add your event-based entity providers here -+ providers.push( -+ BitbucketCloudEntityProvider.fromConfig(env.config, { -+ catalogApi: new CatalogClient({ discoveryApi: env.discovery }), -+ logger: env.logger, -+ scheduler: env.scheduler, -+ tokenManager: env.tokenManager, -+ }), -+ ); +export default async function createCatalogEventBasedProviders( + /* highlight-remove-next-line */ + _: PluginEnvironment, + /* highlight-add-next-line */ + env: PluginEnvironment, +): Promise> { + const providers: Array< + (EntityProvider & EventSubscriber) | Array + > = []; + // add your event-based entity providers here + /* highlight-add-start */ + providers.push( + BitbucketCloudEntityProvider.fromConfig(env.config, { + catalogApi: new CatalogClient({ discoveryApi: env.discovery }), + logger: env.logger, + scheduler: env.scheduler, + tokenManager: env.tokenManager, + }), + ); + /* highlight-add-end */ return providers.flat(); } ``` @@ -111,9 +121,7 @@ Very likely a `username` and `appPassword` will be required Additionally, you need to configure your entity provider instance(s): -```yaml -# app-config.yaml - +```yaml title="app-config.yaml" catalog: providers: bitbucketCloud: diff --git a/docs/integrations/bitbucketServer/discovery.md b/docs/integrations/bitbucketServer/discovery.md index db1cc43ea4..05d0510553 100644 --- a/docs/integrations/bitbucketServer/discovery.md +++ b/docs/integrations/bitbucketServer/discovery.md @@ -26,29 +26,31 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-bitbuck And then add the entity provider to your catalog builder: -```diff - // In packages/backend/src/plugins/catalog.ts -+ import { BitbucketServerEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-server'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { BitbucketServerEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-server'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); -+ builder.addEntityProvider( -+ BitbucketServerEntityProvider.fromConfig(env.config, { -+ logger: env.logger, -+ // optional: alternatively, use scheduler with schedule defined in app-config.yaml -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 30 }, -+ timeout: { minutes: 3 }, -+ }), -+ // optional: alternatively, use schedule -+ scheduler: env.scheduler, -+ }), -+ ); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-start */ + builder.addEntityProvider( + BitbucketServerEntityProvider.fromConfig(env.config, { + logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule + scheduler: env.scheduler, + }), + ); + /* highlight-add-end */ - // [...] - } + // .. +} ``` ## Configuration @@ -57,9 +59,7 @@ To use the entity provider, you'll need a [Bitbucket Server integration set up]( Additionally, you need to configure your entity provider instance(s): -```yaml -# app-config.yaml - +```yaml title="app-config.yaml" catalog: providers: bitbucketServer: diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index bbbe86a834..499cb32812 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -28,37 +28,39 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-github And then add the entity provider to your catalog builder: -```diff - // In packages/backend/src/plugins/catalog.ts -+ import { GithubEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { GithubEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); -+ builder.addEntityProvider( -+ GithubEntityProvider.fromConfig(env.config, { -+ logger: env.logger, -+ // optional: alternatively, use scheduler with schedule defined in app-config.yaml -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 30 }, -+ timeout: { minutes: 3 }, -+ }), -+ // optional: alternatively, use schedule -+ scheduler: env.scheduler, -+ }), -+ ); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-start */ + builder.addEntityProvider( + GithubEntityProvider.fromConfig(env.config, { + logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule + scheduler: env.scheduler, + }), + ); + /* highlight-add-end */ - // [...] - } + // .. +} ``` ## Installation with Events Support Please follow the installation instructions at -- https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md -- https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-github/README.md +- +- Additionally, you need to decide how you want to receive events from external sources like @@ -67,34 +69,38 @@ Additionally, you need to decide how you want to receive events from external so Set up your provider -```diff -// packages/backend/src/plugins/catalogEventBasedProviders.ts -+import { GithubEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; - import { EntityProvider } from '@backstage/plugin-catalog-node'; - import { EventSubscriber } from '@backstage/plugin-events-node'; - import { PluginEnvironment } from '../types'; - export default async function createCatalogEventBasedProviders( -- _: PluginEnvironment, -+ env: PluginEnvironment, - ): Promise> { - const providers: Array< - (EntityProvider & EventSubscriber) | Array - > = []; -- // add your event-based entity providers here -+ providers.push( -+ GithubEntityProvider.fromConfig(env.config, { -+ logger: env.logger, -+ // optional: alternatively, use scheduler with schedule defined in app-config.yaml -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 30 }, -+ timeout: { minutes: 3 }, -+ }), -+ // optional: alternatively, use schedule -+ scheduler: env.scheduler, -+ }), -+ ); - return providers.flat(); - } +```ts title="packages/backend/src/plugins/catalogEventBasedProviders.ts" +/* highlight-add-next-line */ +import { GithubEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; +import { EntityProvider } from '@backstage/plugin-catalog-node'; +import { EventSubscriber } from '@backstage/plugin-events-node'; +import { PluginEnvironment } from '../types'; +export default async function createCatalogEventBasedProviders( + /* highlight-remove-next-line */ + _: PluginEnvironment, + /* highlight-add-next-line */ + env: PluginEnvironment, +): Promise> { + const providers: Array< + (EntityProvider & EventSubscriber) | Array + > = []; + // add your event-based entity providers here + /* highlight-add-start */ + providers.push( + GithubEntityProvider.fromConfig(env.config, { + logger: env.logger, + // optional: alternatively, use scheduler with schedule defined in app-config.yaml + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 30 }, + timeout: { minutes: 3 }, + }), + // optional: alternatively, use schedule + scheduler: env.scheduler, + }), + ); + /* highlight-add-end */ + return providers.flat(); +} ``` You can check the official docs to [configure your webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks) and to [secure your request](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks). The webhook will need to be configured to forward `push` events. @@ -255,34 +261,40 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-github And then add the processors to your catalog builder: -```diff -// In packages/backend/src/plugins/catalog.ts -+import { -+ GithubDiscoveryProcessor, -+ GithubOrgReaderProcessor, -+} from '@backstage/plugin-catalog-backend-module-github'; -+import { -+ ScmIntegrations, -+ DefaultGithubCredentialsProvider -+} from '@backstage/integration'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-start */ +import { + GithubDiscoveryProcessor, + GithubOrgReaderProcessor, +} from '@backstage/plugin-catalog-backend-module-github'; +import { + ScmIntegrations, + DefaultGithubCredentialsProvider +} from '@backstage/integration'; +/* highlight-add-end */ - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); -+ const integrations = ScmIntegrations.fromConfig(env.config); -+ const githubCredentialsProvider = -+ DefaultGithubCredentialsProvider.fromIntegrations(integrations); -+ builder.addProcessor( -+ GithubDiscoveryProcessor.fromConfig(env.config, { -+ logger: env.logger, -+ githubCredentialsProvider, -+ }), -+ GithubOrgReaderProcessor.fromConfig(env.config, { -+ logger: env.logger, -+ githubCredentialsProvider, -+ }), -+ ); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-start */ + const integrations = ScmIntegrations.fromConfig(env.config); + const githubCredentialsProvider = + DefaultGithubCredentialsProvider.fromIntegrations(integrations); + builder.addProcessor( + GithubDiscoveryProcessor.fromConfig(env.config, { + logger: env.logger, + githubCredentialsProvider, + }), + GithubOrgReaderProcessor.fromConfig(env.config, { + logger: env.logger, + githubCredentialsProvider, + }), + ); + /* highlight-add-end */ + + // .. +} ``` ## Configuration diff --git a/docs/integrations/github/org.md b/docs/integrations/github/org.md index 0aa9997bae..4600d65466 100644 --- a/docs/integrations/github/org.md +++ b/docs/integrations/github/org.md @@ -36,36 +36,41 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-github Update the catalog plugin initialization in your backend to add the provider and schedule it: -```diff - // packages/backend/src/plugins/catalog.ts -+import { GithubOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { GithubOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); -+ // The org URL below needs to match a configured integrations.github entry -+ // specified in your app-config. -+ builder.addEntityProvider( -+ GithubOrgEntityProvider.fromConfig(env.config, { -+ id: 'production', -+ orgUrl: 'https://github.com/backstage', -+ logger: env.logger, -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 60 }, -+ timeout: { minutes: 15 }, -+ }), -+ }), -+ ); + /* highlight-add-start */ + // The org URL below needs to match a configured integrations.github entry + // specified in your app-config. + builder.addEntityProvider( + GithubOrgEntityProvider.fromConfig(env.config, { + id: 'production', + orgUrl: 'https://github.com/backstage', + logger: env.logger, + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 60 }, + timeout: { minutes: 15 }, + }), + }), + ); + /* highlight-add-end */ + + // .. +} ``` ## Installation with Events Support Please follow the installation instructions at -- https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md -- https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-github/README.md +- +- Additionally, you need to decide how you want to receive events from external sources like @@ -74,33 +79,37 @@ Additionally, you need to decide how you want to receive events from external so Set up your provider -```diff -// packages/backend/src/plugins/catalogEventBasedProviders.ts -+import { GithubOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; - import { EntityProvider } from '@backstage/plugin-catalog-node'; - import { EventSubscriber } from '@backstage/plugin-events-node'; - import { PluginEnvironment } from '../types'; - export default async function createCatalogEventBasedProviders( -- _: PluginEnvironment, -+ env: PluginEnvironment, - ): Promise> { - const providers: Array< - (EntityProvider & EventSubscriber) | Array - > = []; -- // add your event-based entity providers here -+ providers.push( -+ GithubOrgEntityProvider.fromConfig(env.config, { -+ id: 'production', -+ orgUrl: 'https://github.com/backstage', -+ logger: env.logger, -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 60 }, -+ timeout: { minutes: 15 }, -+ }), -+ }), -+ ); - return providers.flat(); - } +```ts title="packages/backend/src/plugins/catalogEventBasedProviders.ts" +/* highlight-add-next-line */ +import { GithubOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-github'; +import { EntityProvider } from '@backstage/plugin-catalog-node'; +import { EventSubscriber } from '@backstage/plugin-events-node'; +import { PluginEnvironment } from '../types'; +export default async function createCatalogEventBasedProviders( + /* highlight-remove-next-line */ + _: PluginEnvironment, + /* highlight-add-next-line */ + env: PluginEnvironment, +): Promise> { + const providers: Array< + (EntityProvider & EventSubscriber) | Array + > = []; + // add your event-based entity providers here + /* highlight-add-start */ + providers.push( + GithubOrgEntityProvider.fromConfig(env.config, { + id: 'production', + orgUrl: 'https://github.com/backstage', + logger: env.logger, + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 60 }, + timeout: { minutes: 15 }, + }), + }), + ); + /* highlight-add-end */ + return providers.flat(); +} ``` You can check the official docs to [configure your webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks) and to [secure your request](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks). @@ -193,8 +202,7 @@ async (user, ctx): Promise => { Once you have imported the emails you can resolve users in your sign-in in resolver using the catalog entity search via email -```typescript -// packages/backend/src/plugins/auth.ts +```typescript title="packages/backend/src/plugins/auth.ts" ctx.signInWithCatalogUser({ filter: { kind: ['User'], @@ -223,10 +231,9 @@ install and register it in the catalog plugin: yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-github ``` -```typescript -// packages/backend/src/plugins/catalog.ts +```typescript title="packages/backend/src/plugins/catalog.ts" import { GithubOrgReaderProcessor } from '@backstage/plugin-catalog-backend-module-github'; -// ... + builder.addProcessor( GithubOrgReaderProcessor.fromConfig(env.config, { logger: env.logger }), ); diff --git a/docs/integrations/gitlab/discovery.md b/docs/integrations/gitlab/discovery.md index 4c448d3892..8c95243b04 100644 --- a/docs/integrations/gitlab/discovery.md +++ b/docs/integrations/gitlab/discovery.md @@ -42,9 +42,7 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-gitlab Once you've done that, you'll also need to add the segment below to `packages/backend/src/plugins/catalog.ts`: -```ts -/* packages/backend/src/plugins/catalog.ts */ - +```ts title="packages/backend/src/plugins/catalog.ts" import { GitlabDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab'; const builder = await CatalogBuilder.create(env); @@ -91,17 +89,22 @@ The target is composed of three parts: Finally, you will have to add the processor in the catalog initialization code of your backend. -```diff -// In packages/backend/src/plugins/catalog.ts -+import { GitLabDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-gitlab'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { GitLabDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-gitlab'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); -+ builder.addProcessor( -+ GitLabDiscoveryProcessor.fromConfig(env.config, { logger: env.logger }) -+ ); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); + /* highlight-add-start */ + builder.addProcessor( + GitLabDiscoveryProcessor.fromConfig(env.config, { logger: env.logger }) + ); + /* highlight-add-end */ + + // .. +} ``` If you don't want create location object if file with component definition do not exists in project, you can set the `skipReposWithoutExactFileMatch` option. That can reduce count of request to gitlab with 404 status code. diff --git a/docs/integrations/ldap/org.md b/docs/integrations/ldap/org.md index f8b9a18c55..7306ab4105 100644 --- a/docs/integrations/ldap/org.md +++ b/docs/integrations/ldap/org.md @@ -35,28 +35,33 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-ldap Update the catalog plugin initialization in your backend to add the provider and schedule it: -```diff - // packages/backend/src/plugins/catalog.ts -+import { LdapOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-ldap'; +```ts title="packages/backend/src/plugins/catalog.ts" +/* highlight-add-next-line */ +import { LdapOrgEntityProvider } from '@backstage/plugin-catalog-backend-module-ldap'; - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - const builder = await CatalogBuilder.create(env); +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const builder = await CatalogBuilder.create(env); -+ // The target parameter below needs to match the ldap.providers.target -+ // value specified in your app-config. -+ builder.addEntityProvider( -+ LdapOrgEntityProvider.fromConfig(env.config, { -+ id: 'our-ldap-master', -+ target: 'ldaps://ds.example.net', -+ logger: env.logger, -+ schedule: env.scheduler.createScheduledTaskRunner({ -+ frequency: { minutes: 60 }, -+ timeout: { minutes: 15 }, -+ }), -+ }), -+ ); + /* highlight-add-start */ + // The target parameter below needs to match the ldap.providers.target + // value specified in your app-config. + builder.addEntityProvider( + LdapOrgEntityProvider.fromConfig(env.config, { + id: 'our-ldap-master', + target: 'ldaps://ds.example.net', + logger: env.logger, + schedule: env.scheduler.createScheduledTaskRunner({ + frequency: { minutes: 60 }, + timeout: { minutes: 15 }, + }), + }), + ); + /* highlight-add-end */ + + // .. +} ``` After this, you also have to add some configuration in your app-config that @@ -345,8 +350,7 @@ frequency with which they are refreshed, separately from other processors. The `LdapOrgReaderProcessor` is not registered by default, so you have to register it in the catalog plugin: -```typescript -// packages/backend/src/plugins/catalog.ts +```typescript title="packages/backend/src/plugins/catalog.ts" builder.addProcessor( LdapOrgReaderProcessor.fromConfig(env.config, { logger: env.logger, diff --git a/docs/permissions/custom-rules.md b/docs/permissions/custom-rules.md index d82836b9ae..cab138ed9e 100644 --- a/docs/permissions/custom-rules.md +++ b/docs/permissions/custom-rules.md @@ -10,7 +10,7 @@ For some use cases, you may want to define custom [rules](./concepts.md#resource Plugins should export a rule factory that provides type-safety that ensures compatibility with the plugin's backend. The catalog plugin exports `createCatalogPermissionRule` from `@backstage/plugin-catalog-backend/alpha` for this purpose. Note: the `/alpha` path segment is temporary until this API is marked as stable. For this example, we'll define the rule in `packages/backend/src/plugins/permission.ts`, but you can put it anywhere that's accessible by your `backend` package. -```typescript +```typescript title="packages/backend/src/plugins/permission.ts" import type { Entity } from '@backstage/catalog-model'; import { createCatalogPermissionRule } from '@backstage/plugin-catalog-backend/alpha'; import { createConditionFactory } from '@backstage/plugin-permission-node'; @@ -51,9 +51,7 @@ Now that we have a custom rule defined, we need provide it to the catalog plugin The api for providing custom rules may differ between plugins, but there should typically be some integration point during the creation of the backend router. For the catalog, this integration point is exposed via `CatalogBuilder.addPermissionRules`. -```typescript -// packages/backend/src/plugins/catalog.ts - +```typescript title="packages/backend/src/plugins/catalog.ts" import { isInSystemRule } from './permission'; // The CatalogBuilder with the addPermissionRules function is in the alpha path import { CatalogBuilder } from '@backstage/plugin-catalog-backend/alpha'; @@ -76,12 +74,9 @@ The new rule is now ready for use in a permission policy! Let's bring this all together by extending the example policy from the previous section. -```diff -// packages/backend/src/plugins/permission.ts - -+ import { isInSystem } from './catalog'; - -... +```ts title="packages/backend/src/plugins/permission.ts" +/* highlight-add-next-line */ +import { isInSystem } from './catalog'; class TestPermissionPolicy implements PermissionPolicy { async handle( @@ -91,17 +86,21 @@ class TestPermissionPolicy implements PermissionPolicy { if (isResourcePermission(request.permission, 'catalog-entity')) { return createCatalogConditionalDecision( request.permission, -- catalogConditions.isEntityOwner({ -- claims: user?.identity.ownershipEntityRefs ?? [], -- }), -+ { -+ anyOf: [ -+ catalogConditions.isEntityOwner({ -+ claims: user?.identity.ownershipEntityRefs ?? [] -+ }), -+ isInSystem('interviewing') -+ ] -+ } + /* highlight-remove-start */ + catalogConditions.isEntityOwner({ + claims: user?.identity.ownershipEntityRefs ?? [], + }), + /* highlight-remove-end */ + /* highlight-add-start */ + { + anyOf: [ + catalogConditions.isEntityOwner({ + claims: user?.identity.ownershipEntityRefs ?? [] + }), + isInSystem('interviewing') + ] + } + /* highlight-add-end */ ); } diff --git a/docs/permissions/frontend-integration.md b/docs/permissions/frontend-integration.md index d7302f9083..1e83f8ad7d 100644 --- a/docs/permissions/frontend-integration.md +++ b/docs/permissions/frontend-integration.md @@ -12,27 +12,29 @@ However, there are some cases where the integrator needs to supplement the polic If your Backstage permission policy may return a `DENY` for users requesting the `catalogEntityCreatePermission`, it may make sense, for example, to remove access to the `/catalog-import` page entirely: -```diff -// packages/app/src/App.tsx - -... - -+ import { RequirePermission } from '@backstage/plugin-permission-react'; -+ import { catalogEntityCreatePermission } from '@backstage/plugin-catalog-common'; - -... - -- } /> -+ -+ -+ -+ } -+ /> -... +```tsx title="packages/app/src/App.tsx" +/* highlight-add-start */ +import { RequirePermission } from '@backstage/plugin-permission-react'; +import { catalogEntityCreatePermission } from '@backstage/plugin-catalog-common'; +/* highlight-add-end */ +const routes = ( + + {/* highlight-remove-next-line */} + } /> + {/* highlight-add-start */} + + + + } + /> + {/* highlight-add-end */} + {/* ... */} + +); ``` With this change, users who are denied the `catalogEntityCreatePermission` should now be unable to access the `/catalog-import` page. diff --git a/docs/permissions/getting-started.md b/docs/permissions/getting-started.md index e71601b703..76cccbdf38 100644 --- a/docs/permissions/getting-started.md +++ b/docs/permissions/getting-started.md @@ -46,64 +46,67 @@ The permissions framework uses a new `permission-backend` plugin to accept autho 1. Add `@backstage/plugin-permission-backend` as a dependency of your Backstage backend: -```bash -# From your Backstage root directory -$ yarn add --cwd packages/backend @backstage/plugin-permission-backend -``` + ```bash + # From your Backstage root directory + $ yarn add --cwd packages/backend @backstage/plugin-permission-backend + ``` 2. Add the following to a new file, `packages/backend/src/plugins/permission.ts`. This adds the permission-backend router, and configures it with a policy which allows everything. -```typescript -import { createRouter } from '@backstage/plugin-permission-backend'; -import { - AuthorizeResult, - PolicyDecision, -} from '@backstage/plugin-permission-common'; -import { PermissionPolicy } from '@backstage/plugin-permission-node'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; + ```typescript title="packages/backend/src/plugins/permission.ts" + import { createRouter } from '@backstage/plugin-permission-backend'; + import { + AuthorizeResult, + PolicyDecision, + } from '@backstage/plugin-permission-common'; + import { PermissionPolicy } from '@backstage/plugin-permission-node'; + import { Router } from 'express'; + import { PluginEnvironment } from '../types'; -class TestPermissionPolicy implements PermissionPolicy { - async handle(): Promise { - return { result: AuthorizeResult.ALLOW }; - } -} + class TestPermissionPolicy implements PermissionPolicy { + async handle(): Promise { + return { result: AuthorizeResult.ALLOW }; + } + } -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - return await createRouter({ - config: env.config, - logger: env.logger, - discovery: env.discovery, - policy: new TestPermissionPolicy(), - identity: env.identity, - }); -} -``` + export default async function createPlugin( + env: PluginEnvironment, + ): Promise { + return await createRouter({ + config: env.config, + logger: env.logger, + discovery: env.discovery, + policy: new TestPermissionPolicy(), + identity: env.identity, + }); + } + ``` 3. Wire up the permission policy in `packages/backend/src/index.ts`. [The index in the example backend](https://github.com/backstage/backstage/blob/master/packages/backend/src/index.ts) shows how to do this. You’ll need to import the module from the previous step, create a plugin environment, and add the router to the express app: -```diff - import proxy from './plugins/proxy'; - import techdocs from './plugins/techdocs'; - import search from './plugins/search'; -+ import permission from './plugins/permission'; + ```ts title="packages/backend/src/index.ts" + import proxy from './plugins/proxy'; + import techdocs from './plugins/techdocs'; + import search from './plugins/search'; + /* highlight-add-next-line */ + import permission from './plugins/permission'; - ... + async function main() { + const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs')); + const searchEnv = useHotMemoize(module, () => createEnv('search')); + const appEnv = useHotMemoize(module, () => createEnv('app')); + /* highlight-add-next-line */ + const permissionEnv = useHotMemoize(module, () => createEnv('permission')); + // .. - const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs')); - const searchEnv = useHotMemoize(module, () => createEnv('search')); - const appEnv = useHotMemoize(module, () => createEnv('app')); -+ const permissionEnv = useHotMemoize(module, () => createEnv('permission')); - - ... - - apiRouter.use('/techdocs', await techdocs(techdocsEnv)); - apiRouter.use('/proxy', await proxy(proxyEnv)); - apiRouter.use('/search', await search(searchEnv)); -+ apiRouter.use('/permission', await permission(permissionEnv)); -``` + apiRouter.use('/techdocs', await techdocs(techdocsEnv)); + apiRouter.use('/proxy', await proxy(proxyEnv)); + apiRouter.use('/search', await search(searchEnv)); + /* highlight-add-next-line */ + apiRouter.use('/permission', await permission(permissionEnv)); + // .. + } + ``` ### 2. Enable and test the permissions system @@ -111,40 +114,46 @@ Now that the permission backend is running, it’s time to enable the permission 1. Set the property `permission.enabled` to `true` in `app-config.yaml`. -```yaml -permission: - enabled: true -``` + ```yaml title="app-config.yaml" + permission: + enabled: true + ``` 2. Update the PermissionPolicy in `packages/backend/src/plugins/permission.ts` to disable a permission that’s easy for us to test. This policy rejects any attempt to delete a catalog entity: -```diff - import { createRouter } from '@backstage/plugin-permission-backend'; - import { - AuthorizeResult, - PolicyDecision, - } from '@backstage/plugin-permission-common'; -- import { PermissionPolicy } from '@backstage/plugin-permission-node'; -+ import { -+ PermissionPolicy, -+ PolicyQuery, -+ } from '@backstage/plugin-permission-node'; - import { Router } from 'express'; - import { PluginEnvironment } from '../types'; + ```ts title="packages/backend/src/plugins/permission.ts" + import { createRouter } from '@backstage/plugin-permission-backend'; + import { + AuthorizeResult, + PolicyDecision, + } from '@backstage/plugin-permission-common'; + /* highlight-remove-next-line */ + import { PermissionPolicy } from '@backstage/plugin-permission-node'; + /* highlight-add-start */ + import { + PermissionPolicy, + PolicyQuery, + } from '@backstage/plugin-permission-node'; + /* highlight-add-end */ + import { Router } from 'express'; + import { PluginEnvironment } from '../types'; - class TestPermissionPolicy implements PermissionPolicy { -- async handle(): Promise { -+ async handle(request: PolicyQuery): Promise { -+ if (request.permission.name === 'catalog.entity.delete') { -+ return { -+ result: AuthorizeResult.DENY, -+ }; -+ } -+ - return { result: AuthorizeResult.ALLOW }; + class TestPermissionPolicy implements PermissionPolicy { + /* highlight-remove-next-line */ + async handle(): Promise { + /* highlight-add-start */ + async handle(request: PolicyQuery): Promise { + if (request.permission.name === 'catalog.entity.delete') { + return { + result: AuthorizeResult.DENY, + }; + } + /* highlight-add-end */ + + return { result: AuthorizeResult.ALLOW }; + } } - } -``` + ``` 3. Now that you’ve made this change, you should find that the unregister entity menu option on the catalog entity page is disabled. diff --git a/docs/permissions/plugin-authors/01-setup.md b/docs/permissions/plugin-authors/01-setup.md index c368505849..46673ed307 100644 --- a/docs/permissions/plugin-authors/01-setup.md +++ b/docs/permissions/plugin-authors/01-setup.md @@ -18,7 +18,7 @@ The source code is available here: - [todo-list-backend](https://github.com/backstage/backstage/blob/master/plugins/example-todo-list-backend) - [todo-list-common](https://github.com/backstage/backstage/blob/master/plugins/example-todo-list-common) -1. Copy-paste the three folders into the plugins folder of your backstage application repository (removing the `example-` prefix from each folder) or run the following script from the root of your backstage application: +1. Copy-paste the three folders into the plugins folder of your backstage application repository (removing the `example-` prefix from each folder) or run the following script from the root of your backstage application: ```bash $ cd $(mktemp -d) @@ -37,7 +37,7 @@ The source code is available here: **Important**: if you are on **Windows**, make sure you have WSL and git installed on your machine before executing the script above. -2. Add these packages as dependencies for your Backstage app: +2. Add these packages as dependencies for your Backstage app: ```sh # From your Backstage root directory @@ -45,11 +45,11 @@ The source code is available here: $ yarn add --cwd packages/app @internal/plugin-todo-list ``` -3. Include the backend and frontend plugin in your application: +3. Include the backend and frontend plugin in your application: Create a new `packages/backend/src/plugins/todolist.ts` with the following content: - ```typescript + ```typescript title="packages/backend/src/plugins/todolist.ts" import { DefaultIdentityClient } from '@backstage/plugin-auth-node'; import { createRouter } from '@internal/plugin-todo-list-backend'; import { Router } from 'express'; @@ -71,40 +71,47 @@ The source code is available here: Apply the following changes to `packages/backend/src/index.ts`: - ```diff - import techdocs from './plugins/techdocs'; - + import todoList from './plugins/todolist'; - import search from './plugins/search'; - - ... + ```ts title="packages/backend/src/index.ts" + import techdocs from './plugins/techdocs'; + /* highlight-add-next-line */ + import todoList from './plugins/todolist'; + import search from './plugins/search'; + async function main() { const searchEnv = useHotMemoize(module, () => createEnv('search')); const appEnv = useHotMemoize(module, () => createEnv('app')); - + const todoListEnv = useHotMemoize(module, () => createEnv('todolist')); - - ... + /* highlight-add-next-line */ + const todoListEnv = useHotMemoize(module, () => createEnv('todolist')); + // .. apiRouter.use('/proxy', await proxy(proxyEnv)); apiRouter.use('/search', await search(searchEnv)); apiRouter.use('/permission', await permission(permissionEnv)); - + apiRouter.use('/todolist', await todoList(todoListEnv)); + /* highlight-add-next-line */ + apiRouter.use('/todolist', await todoList(todoListEnv)); // Add backends ABOVE this line; this 404 handler is the catch-all fallback apiRouter.use(notFoundHandler()); + // .. + } ``` Apply the following changes to `packages/app/src/App.tsx`: - ```diff - + import { TodoListPage } from '@internal/plugin-todo-list'; - - ... + ```tsx title="packages/app/src/App.tsx" + /* highlight-add-next-line */ + import { TodoListPage } from '@internal/plugin-todo-list'; + const routes = ( + }> {searchPage} } /> - + } /> + {/* highlight-add-next-line */} + } /> + {/* ... */} + ); ``` Now if you start your application you should be able to reach the `/todo-list` page: diff --git a/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md b/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md index 44a3e43718..837be197cf 100644 --- a/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md +++ b/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md @@ -14,19 +14,25 @@ We'll start by creating a new permission, and then we'll use the permission api Let's navigate to the file `plugins/todo-list-common/src/permissions.ts` and add our first permission: -```diff - import { createPermission } from '@backstage/plugin-permission-common'; +```ts title="plugins/todo-list-common/src/permissions.ts" +import { createPermission } from '@backstage/plugin-permission-common'; -- export const tempExamplePermission = createPermission({ -- name: 'temp.example.noop', -- attributes: {}, -+ export const todoListCreatePermission = createPermission({ -+ name: 'todo.list.create', -+ attributes: { action: 'create' }, - }); +/* highlight-remove-start */ +export const tempExamplePermission = createPermission({ + name: 'temp.example.noop', + attributes: {}, +/* highlight-remove-end */ +/* highlight-add-start */ +export const todoListCreatePermission = createPermission({ + name: 'todo.list.create', + attributes: { action: 'create' }, +/* highlight-add-end */ +}); -- export const todoListPermissions = [tempExamplePermission]; -+ export const todoListPermissions = [todoListCreatePermission]; +/* highlight-remove-next-line */ +export const todoListPermissions = [tempExamplePermission]; +/* highlight-add-next-line */ +export const todoListPermissions = [todoListCreatePermission]; ``` For this tutorial, we've automatically exported all permissions from this file (see `plugins/todo-list-common/src/index.ts`). @@ -44,81 +50,86 @@ $ yarn workspace @internal/plugin-todo-list-backend \ Edit `plugins/todo-list-backend/src/service/router.ts`: -```diff -... +```ts title="plugins/todo-list-backend/src/service/router.ts" +/* highlight-remove-start */ +import { InputError } from '@backstage/errors'; +import { IdentityApi } from '@backstage/plugin-auth-node'; +/* highlight-remove-end */ +/* highlight-add-start */ +import { InputError, NotAllowedError } from '@backstage/errors'; +import { getBearerTokenFromAuthorizationHeader, IdentityApi } from '@backstage/plugin-auth-node'; +import { PermissionEvaluator, AuthorizeResult } from '@backstage/plugin-permission-common'; +import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +/* highlight-add-end */ -- import { InputError } from '@backstage/errors'; -- import { IdentityApi } from '@backstage/plugin-auth-node'; -+ import { InputError, NotAllowedError } from '@backstage/errors'; -+ import { getBearerTokenFromAuthorizationHeader, IdentityApi } from '@backstage/plugin-auth-node'; -+ import { PermissionEvaluator, AuthorizeResult } from '@backstage/plugin-permission-common'; -+ import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +export interface RouterOptions { + logger: Logger; + identity: IdentityApi; + /* highlight-add-next-line */ + permissions: PermissionEvaluator; +} -... +export async function createRouter( + options: RouterOptions, +): Promise { + /* highlight-remove-next-line */ + const { logger, identity } = options; + /* highlight-add-next-line */ + const { logger, identity, permissions } = options; - export interface RouterOptions { - logger: Logger; - identity: IdentityApi; -+ permissions: PermissionEvaluator; - } + router.post('/todos', async (req, res) => { + let author: string | undefined = undefined; - export async function createRouter( - options: RouterOptions, - ): Promise { -- const { logger, identity } = options; -+ const { logger, identity, permissions } = options; + const user = await identity.getIdentity({ request: req }); + author = user?.identity.userEntityRef; + /* highlight-add-start */ + const token = getBearerTokenFromAuthorizationHeader( + req.header('authorization'), + ); + const decision = ( + await permissions.authorize([{ permission: todoListCreatePermission }], { + token, + }) + )[0]; - ... + if (decision.result === AuthorizeResult.DENY) { + throw new NotAllowedError('Unauthorized'); + } + /* highlight-add-end */ - router.post('/todos', async (req, res) => { - let author: string | undefined = undefined; + if (!isTodoCreateRequest(req.body)) { + throw new InputError('Invalid payload'); + } - const user = await identity.getIdentity({ request: req }); - author = user?.identity.userEntityRef; -+ const token = getBearerTokenFromAuthorizationHeader( -+ req.header('authorization'), -+ ); -+ const decision = ( -+ await permissions.authorize([{ permission: todoListCreatePermission }], { -+ token, -+ }) -+ )[0]; - -+ if (decision.result === AuthorizeResult.DENY) { -+ throw new NotAllowedError('Unauthorized'); -+ } - - if (!isTodoCreateRequest(req.body)) { - throw new InputError('Invalid payload'); - } - - const todo = add({ title: req.body.title, author }); - res.json(todo); - }); + const todo = add({ title: req.body.title, author }); + res.json(todo); +}); ``` Pass the `permissions` object to the plugin in `packages/backend/src/plugins/todolist.ts`: -```diff - import { DefaultIdentityClient } from '@backstage/plugin-auth-node'; - import { createRouter } from '@internal/plugin-todo-list-backend'; - import { Router } from 'express'; - import { PluginEnvironment } from '../types'; +```ts title="packages/backend/src/plugins/todolist.ts" +import { DefaultIdentityClient } from '@backstage/plugin-auth-node'; +import { createRouter } from '@internal/plugin-todo-list-backend'; +import { Router } from 'express'; +import { PluginEnvironment } from '../types'; - export default async function createPlugin({ +export default async function createPlugin({ + logger, + discovery, + /* highlight-add-next-line */ + permissions, +}: PluginEnvironment): Promise { + return await createRouter({ logger, - discovery, -+ permissions, - }: PluginEnvironment): Promise { - return await createRouter({ - logger, - identity: DefaultIdentityClient.create({ - discovery, - issuer: await discovery.getExternalBaseUrl('auth'), - }), -+ permissions, - }); - } + identity: DefaultIdentityClient.create({ + discovery, + issuer: await discovery.getExternalBaseUrl('auth'), + }), + /* highlight-add-next-line */ + permissions, + }); +} ``` That's it! Now your plugin is fully configured. Let's try to test the logic by denying the permission. @@ -129,200 +140,219 @@ Before running this step, please make sure you followed the steps described in [ In order to test the logic above, the integrators of your backstage instance need to change their permission policy to return `DENY` for our newly-created permission: -```diff -// packages/backend/src/plugins/permission.ts +```ts title="packages/backend/src/plugins/permission.ts" +/* highlight-add-start */ +import { + BackstageIdentityResponse, +} from '@backstage/plugin-auth-node'; +/* highlight-add-end */ +import { + PermissionPolicy, + /* highlight-add-next-line */ + PolicyQuery, +} from '@backstage/plugin-permission-node'; +/* highlight-add-start */ +import { isPermission } from '@backstage/plugin-permission-common'; +import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +/* highlight-add-end */ -+ import { -+ BackstageIdentityResponse, -+ } from '@backstage/plugin-auth-node'; - import { - PermissionPolicy, -+ PolicyQuery, - } from '@backstage/plugin-permission-node'; -+ import { isPermission } from '@backstage/plugin-permission-common'; -+ import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; - - class TestPermissionPolicy implements PermissionPolicy { -- async handle(): Promise { -+ async handle( -+ request: PolicyQuery, -+ _user?: BackstageIdentityResponse, -+ ): Promise { -+ if (isPermission(request.permission, todoListCreatePermission)) { -+ return { -+ result: AuthorizeResult.DENY, -+ }; -+ } -+ +class TestPermissionPolicy implements PermissionPolicy { + /* highlight-remove-next-line */ + async handle(): Promise { + /* highlight-add-start */ + async handle( + request: PolicyQuery, + _user?: BackstageIdentityResponse, + ): Promise { + if (isPermission(request.permission, todoListCreatePermission)) { return { - result: AuthorizeResult.ALLOW, + result: AuthorizeResult.DENY, }; - } + } + /* highlight-add-end */ + + return { + result: AuthorizeResult.ALLOW, + }; +} ``` Now the frontend should show an error whenever you try to create a new Todo item. Let's flip the result back to `ALLOW` before moving on. -```diff - if (isPermission(request.permission, todoListCreatePermission)) { - return { -- result: AuthorizeResult.DENY, -+ result: AuthorizeResult.ALLOW, - }; - } +```ts +if (isPermission(request.permission, todoListCreatePermission)) { + return { + /* highlight-remove-next-line */ + result: AuthorizeResult.DENY, + /* highlight-add-next-line */ + result: AuthorizeResult.ALLOW, + }; +} ``` At this point everything is working but if you run `yarn tsc` you'll get some errors, let's fix those up. First we'll clean up the `plugins/todo-list-backend/src/service/router.test.ts`: -```diff - import { getVoidLogger } from '@backstage/backend-common'; - import { DefaultIdentityClient } from '@backstage/plugin-auth-node'; -+ import { PermissionEvaluator } from '@backstage/plugin-permission-common'; - import express from 'express'; - import request from 'supertest'; +```ts title="plugins/todo-list-backend/src/service/router.test.ts" +import { getVoidLogger } from '@backstage/backend-common'; +import { DefaultIdentityClient } from '@backstage/plugin-auth-node'; +/* highlight-add-next-line */ +import { PermissionEvaluator } from '@backstage/plugin-permission-common'; +import express from 'express'; +import request from 'supertest'; - import { createRouter } from './router'; +import { createRouter } from './router'; -+ const mockedAuthorize: jest.MockedFunction = -+ jest.fn(); -+ const mockedPermissionQuery: jest.MockedFunction< -+ PermissionEvaluator['authorizeConditional'] -+ > = jest.fn(); +/* highlight-add-start */ +const mockedAuthorize: jest.MockedFunction = + jest.fn(); +const mockedPermissionQuery: jest.MockedFunction< + PermissionEvaluator['authorizeConditional'] +> = jest.fn(); -+ const permissionEvaluator: PermissionEvaluator = { -+ authorize: mockedAuthorize, -+ authorizeConditional: mockedPermissionQuery, -+ }; +const permissionEvaluator: PermissionEvaluator = { + authorize: mockedAuthorize, + authorizeConditional: mockedPermissionQuery, +}; +/* highlight-add-end */ - describe('createRouter', () => { - let app: express.Express; +describe('createRouter', () => { + let app: express.Express; - beforeAll(async () => { - const router = await createRouter({ - logger: getVoidLogger(), - identity: {} as DefaultIdentityClient, -+ permissions: permissionEvaluator, - }); - app = express().use(router); - }); - - beforeEach(() => { - jest.resetAllMocks(); - }); - - describe('GET /health', () => { - it('returns ok', async () => { - const response = await request(app).get('/health'); - - expect(response.status).toEqual(200); - expect(response.body).toEqual({ status: 'ok' }); - }); + beforeAll(async () => { + const router = await createRouter({ + logger: getVoidLogger(), + identity: {} as DefaultIdentityClient, + /* highlight-add-next-line */ + permissions: permissionEvaluator, }); + app = express().use(router); }); + beforeEach(() => { + jest.resetAllMocks(); + }); + + describe('GET /health', () => { + it('returns ok', async () => { + const response = await request(app).get('/health'); + + expect(response.status).toEqual(200); + expect(response.body).toEqual({ status: 'ok' }); + }); + }); +}); ``` Then we want to update the `plugins/todo-list-backend/src/service/standaloneServer.ts`, first we need to add the `@backstage/plugin-permission-node` package to `plugins/todo-list-backend/package.json` and then we can make the following edits: -```diff - import { - createServiceBuilder, - loadBackendConfig, - SingleHostDiscovery, -+ ServerTokenManager, - } from '@backstage/backend-common'; - import { DefaultIdentityClient } from '@backstage/plugin-auth-node'; -+ import { ServerPermissionClient } from '@backstage/plugin-permission-node'; - import { Server } from 'http'; - import { Logger } from 'winston'; - import { createRouter } from './router'; +```ts title="plugins/todo-list-backend/src/service/standaloneServer.ts" +import { + createServiceBuilder, + loadBackendConfig, + SingleHostDiscovery, + /* highlight-add-next-line */ + ServerTokenManager, +} from '@backstage/backend-common'; +import { DefaultIdentityClient } from '@backstage/plugin-auth-node'; +/* highlight-add-next-line */ +import { ServerPermissionClient } from '@backstage/plugin-permission-node'; +import { Server } from 'http'; +import { Logger } from 'winston'; +import { createRouter } from './router'; - export interface ServerOptions { - port: number; - enableCors: boolean; - logger: Logger; +export interface ServerOptions { + port: number; + enableCors: boolean; + logger: Logger; +} + +export async function startStandaloneServer( + options: ServerOptions, +): Promise { + const logger = options.logger.child({ service: 'todo-list-backend' }); + logger.debug('Starting application server...'); + const config = await loadBackendConfig({ logger, argv: process.argv }); + const discovery = SingleHostDiscovery.fromConfig(config); + /* highlight-add-start */ + const tokenManager = ServerTokenManager.fromConfig(config, { + logger, + }); + const permissions = ServerPermissionClient.fromConfig(config, { + discovery, + tokenManager, + }); + /* highlight-add-end */ + const router = await createRouter({ + logger, + identity: DefaultIdentityClient.create({ + discovery, + issuer: await discovery.getExternalBaseUrl('auth'), + }), + /* highlight-add-next-line */ + permissions, + }); + + let service = createServiceBuilder(module) + .setPort(options.port) + .addRouter('/todo-list', router); + if (options.enableCors) { + service = service.enableCors({ origin: 'http://localhost:3000' }); } - export async function startStandaloneServer( - options: ServerOptions, - ): Promise { - const logger = options.logger.child({ service: 'todo-list-backend' }); - logger.debug('Starting application server...'); - const config = await loadBackendConfig({ logger, argv: process.argv }); - const discovery = SingleHostDiscovery.fromConfig(config); -+ const tokenManager = ServerTokenManager.fromConfig(config, { -+ logger, -+ }); -+ const permissions = ServerPermissionClient.fromConfig(config, { -+ discovery, -+ tokenManager, -+ }); - const router = await createRouter({ - logger, - identity: DefaultIdentityClient.create({ - discovery, - issuer: await discovery.getExternalBaseUrl('auth'), - }), -+ permissions, - }); + return await service.start().catch(err => { + logger.error(err); + process.exit(1); + }); +} - let service = createServiceBuilder(module) - .setPort(options.port) - .addRouter('/todo-list', router); - if (options.enableCors) { - service = service.enableCors({ origin: 'http://localhost:3000' }); - } - - return await service.start().catch(err => { - logger.error(err); - process.exit(1); - }); - } - - module.hot?.accept(); +module.hot?.accept(); ``` Finally, we need to update `plugins/todo-list-backend/src/plugin.ts`: -```diff - import { loggerToWinstonLogger } from '@backstage/backend-common'; - import { - coreServices, - createBackendPlugin, - } from '@backstage/backend-plugin-api'; - import { createRouter } from './service/router'; +```ts title="plugins/todo-list-backend/src/plugin.ts" +import { loggerToWinstonLogger } from '@backstage/backend-common'; +import { + coreServices, + createBackendPlugin, +} from '@backstage/backend-plugin-api'; +import { createRouter } from './service/router'; - /** - * The example TODO list backend plugin. - * - * @alpha - */ - export const exampleTodoListPlugin = createBackendPlugin({ - pluginId: 'exampleTodoList', - register(env) { - env.registerInit({ - deps: { - identity: coreServices.identity, - logger: coreServices.logger, - httpRouter: coreServices.httpRouter, -+ permissions: coreServices.permissions, - }, -- async init({ identity, logger, httpRouter }) { -+ async init({ identity, logger, httpRouter, permissions }) { - httpRouter.use( - await createRouter({ - identity, - logger: loggerToWinstonLogger(logger), - permissions, - }), - ); - }, - }); - }, - }); +/** +* The example TODO list backend plugin. +* +* @alpha +*/ +export const exampleTodoListPlugin = createBackendPlugin({ + pluginId: 'exampleTodoList', + register(env) { + env.registerInit({ + deps: { + identity: coreServices.identity, + logger: coreServices.logger, + httpRouter: coreServices.httpRouter, + /* highlight-add-next-line */ + permissions: coreServices.permissions, + }, + /* highlight-remove-next-line */ + async init({ identity, logger, httpRouter }) { + /* highlight-add-next-line */ + async init({ identity, logger, httpRouter, permissions }) { + httpRouter.use( + await createRouter({ + identity, + logger: loggerToWinstonLogger(logger), + permissions, + }), + ); + }, + }); + }, +}); ``` Now when you run `yarn tsc` you should have no more errors. diff --git a/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md b/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md index b063727c71..ed4fb74573 100644 --- a/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md +++ b/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md @@ -10,24 +10,29 @@ When performing updates (or other operations) on specific [resources](../concept Let's add a new permission to the file `plugins/todo-list-common/src/permissions.ts` from [the previous section](./02-adding-a-basic-permission-check.md). -```diff - import { createPermission } from '@backstage/plugin-permission-common'; +```ts title="plugins/todo-list-common/src/permissions.ts" +import { createPermission } from '@backstage/plugin-permission-common'; -+ export const TODO_LIST_RESOURCE_TYPE = 'todo-item'; -+ - export const todoListCreatePermission = createPermission({ - name: 'todo.list.create', - attributes: { action: 'create' }, - }); -+ -+ export const todoListUpdatePermission = createPermission({ -+ name: 'todo.list.update', -+ attributes: { action: 'update' }, -+ resourceType: TODO_LIST_RESOURCE_TYPE, -+ }); +/* highlight-add-next-line */ +export const TODO_LIST_RESOURCE_TYPE = 'todo-item'; -- export const todoListPermissions = [todoListCreatePermission]; -+ export const todoListPermissions = [todoListCreatePermission, todoListUpdatePermission]; +export const todoListCreatePermission = createPermission({ + name: 'todo.list.create', + attributes: { action: 'create' }, +}); + +/* highlight-add-start */ +export const todoListUpdatePermission = createPermission({ + name: 'todo.list.update', + attributes: { action: 'update' }, + resourceType: TODO_LIST_RESOURCE_TYPE, +}); +/* highlight-add-end */ + +/* highlight-remove-next-line */ +export const todoListPermissions = [todoListCreatePermission]; +/* highlight-add-next-line */ +export const todoListPermissions = [todoListCreatePermission, todoListUpdatePermission]; ``` Notice that unlike `todoListCreatePermission`, the `todoListUpdatePermission` permission contains a `resourceType` field. This field indicates to the permission framework that this permission is intended to be authorized in the context of a resource with type `'todo-item'`. You can use whatever string you like as the resource type, as long as you use the same value consistently for each type of resource. @@ -36,35 +41,39 @@ Notice that unlike `todoListCreatePermission`, the `todoListUpdatePermission` pe To start, let's edit `plugins/todo-list-backend/src/service/router.ts` in the same manner as we did in the previous section: -```diff -- import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; -+ import { todoListCreatePermission, todoListUpdatePermission } from '@internal/plugin-todo-list-common'; +```ts title="plugins/todo-list-backend/src/service/router.ts" +/* highlight-remove-next-line */ +import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +/* highlight-add-next-line */ +import { todoListCreatePermission, todoListUpdatePermission } from '@internal/plugin-todo-list-common'; - ... +router.put('/todos', async (req, res) => { + /* highlight-add-start */ + const token = getBearerTokenFromAuthorizationHeader( + req.header('authorization'), + ); + /* highlight-add-end */ - router.put('/todos', async (req, res) => { -+ const token = getBearerTokenFromAuthorizationHeader( -+ req.header('authorization'), -+ ); + if (!isTodoUpdateRequest(req.body)) { + throw new InputError('Invalid payload'); + } + /* highlight-add-start */ + const decision = ( + await permissions.authorize( + [{ permission: todoListUpdatePermission, resourceRef: req.body.id }], + { + token, + }, + ) + )[0]; - if (!isTodoUpdateRequest(req.body)) { - throw new InputError('Invalid payload'); - } -+ const decision = ( -+ await permissions.authorize( -+ [{ permission: todoListUpdatePermission, resourceRef: req.body.id }], -+ { -+ token, -+ }, -+ ) -+ )[0]; -+ -+ if (decision.result !== AuthorizeResult.ALLOW) { -+ throw new NotAllowedError('Unauthorized'); -+ } + if (decision.result !== AuthorizeResult.ALLOW) { + throw new NotAllowedError('Unauthorized'); + } + /* highlight-add-end */ - res.json(update(req.body)); - }); + res.json(update(req.body)); +}); ``` **Important:** Notice that we are passing an extra `resourceRef` field, with the `id` of the todo item as the value. @@ -75,13 +84,13 @@ This enables decisions based on characteristics of the resource, but it's import Install the missing module: -``` +```bash $ yarn workspace @internal/plugin-todo-list-backend add @backstage/plugin-permission-node zod ``` Create a new `plugins/todo-list-backend/src/service/rules.ts` file and append the following code: -```typescript +```typescript title="plugins/todo-list-backend/src/service/rules.ts" import { makeCreatePermissionRule } from '@backstage/plugin-permission-node'; import { TODO_LIST_RESOURCE_TYPE } from '@internal/plugin-todo-list-common'; import { z } from 'zod'; @@ -130,35 +139,43 @@ Now, let's create the new endpoint by editing `plugins/todo-list-backend/src/ser - `permissions`: the list of permissions that your plugin accepts. - `rules`: an array of all the permission rules you want to support in conditional decisions. -```diff -... +```ts title="plugins/todo-list-backend/src/service/router.ts" +/* highlight-remove-next-line */ +import { add, getAll, update } from './todos'; +/* highlight-add-start */ +import { add, getAll, getTodo, update } from './todos'; +import { createPermissionIntegrationRouter } from '@backstage/plugin-permission-node'; +import { TODO_LIST_RESOURCE_TYPE, todoListPermissions } from '@internal/plugin-todo-list-common'; +import { rules } from './rules'; +/* highlight-add-end */ -- import { add, getAll, update } from './todos'; -+ import { add, getAll, getTodo, update } from './todos'; -+ import { createPermissionIntegrationRouter } from '@backstage/plugin-permission-node'; -+ import { TODO_LIST_RESOURCE_TYPE, todoListPermissions } from '@internal/plugin-todo-list-common'; -+ import { rules } from './rules'; +export async function createRouter( + options: RouterOptions, +): Promise { + const { logger, identity, permissions } = options; - export async function createRouter( - options: RouterOptions, - ): Promise { - const { logger, identity, permissions } = options; + /* highlight-add-start */ + const permissionIntegrationRouter = createPermissionIntegrationRouter({ + getResources: async resourceRefs => { + return resourceRefs.map(getTodo); + }, + resourceType: TODO_LIST_RESOURCE_TYPE, + permissions: todoListPermissions, + rules: Object.values(rules), + }); + /* highlight-add-end */ -+ const permissionIntegrationRouter = createPermissionIntegrationRouter({ -+ getResources: async resourceRefs => { -+ return resourceRefs.map(getTodo); -+ }, -+ resourceType: TODO_LIST_RESOURCE_TYPE, -+ permissions: todoListPermissions, -+ rules: Object.values(rules), -+ }); + const router = Router(); + router.use(express.json()); - const router = Router(); - router.use(express.json()); + /* highlight-add-next-line */ + router.use(permissionIntegrationRouter); -+ router.use(permissionIntegrationRouter); - - router.post('/todos', async (req, res) => { + router.post('/todos', async (req, res) => { + // .. + } + // .. +} ``` ## Provide utilities for policy authors @@ -167,7 +184,7 @@ Now that we have a new resource type and a corresponding rule, we need to export Create a new `plugins/todo-list-backend/src/conditionExports.ts` file and add the following code: -```typescript +```typescript title="plugins/todo-list-backend/src/conditionExports.ts" import { TODO_LIST_RESOURCE_TYPE } from '@internal/plugin-todo-list-common'; import { createConditionExports } from '@backstage/plugin-permission-node'; import { rules } from './service/rules'; @@ -185,63 +202,68 @@ export const createTodoListConditionalDecision = createConditionalDecision; Make sure `todoListConditions` and `createTodoListConditionalDecision` are exported from the `todo-list-backend` package by editing `plugins/todo-list-backend/src/index.ts`: -```diff - export * from './service/router'; -+ export * from './conditionExports'; - export { exampleTodoListPlugin } from './plugin'; +```ts title="plugins/todo-list-backend/src/index.ts" +export * from './service/router'; +/* highlight-add-next-line */ +export * from './conditionExports'; +export { exampleTodoListPlugin } from './plugin'; ``` ## Test the authorized update endpoint Let's go back to the permission policy's handle function and try to authorize our new permission with an `isOwner` condition. -```diff - // packages/backend/src/plugins/permission.ts +```ts title="packages/backend/src/plugins/permission.ts" +import { + BackstageIdentityResponse, + IdentityClient +} from '@backstage/plugin-auth-node'; +import { + PermissionPolicy, + PolicyQuery, +} from '@backstage/plugin-permission-node'; +import { isPermission } from '@backstage/plugin-permission-common'; +/* highlight-remove-next-line */ +import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +/* highlight-add-start */ +import { + todoListCreatePermission, + todoListUpdatePermission, +} from '@internal/plugin-todo-list-common'; +import { + todoListConditions, + createTodoListConditionalDecision, +} from '@internal/plugin-todo-list-backend'; +/* highlight-add-end */ - import { - BackstageIdentityResponse, - IdentityClient - } from '@backstage/plugin-auth-node'; - import { - PermissionPolicy, - PolicyQuery, - } from '@backstage/plugin-permission-node'; - import { isPermission } from '@backstage/plugin-permission-common'; -- import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; -+ import { -+ todoListCreatePermission, -+ todoListUpdatePermission, -+ } from '@internal/plugin-todo-list-common'; -+ import { -+ todoListConditions, -+ createTodoListConditionalDecision, -+ } from '@internal/plugin-todo-list-backend'; -... - async handle( - request: PolicyQuery, -- _user?: BackstageIdentityResponse, -+ user?: BackstageIdentityResponse, - ): Promise { - if (isPermission(request.permission, todoListCreatePermission)) { - return { - result: AuthorizeResult.ALLOW, - }; - } - -+ if (isPermission(request.permission, todoListUpdatePermission)) { -+ return createTodoListConditionalDecision( -+ request.permission, -+ todoListConditions.isOwner({ -+ userId: user?.identity.userEntityRef ?? '', -+ }), -+ ); -+ } -+ +async handle( + request: PolicyQuery, + /* highlight-remove-next-line */ + _user?: BackstageIdentityResponse, + /* highlight-add-next-line */ + user?: BackstageIdentityResponse, +): Promise { + if (isPermission(request.permission, todoListCreatePermission)) { return { result: AuthorizeResult.ALLOW, }; } + /* highlight-add-start */ + if (isPermission(request.permission, todoListUpdatePermission)) { + return createTodoListConditionalDecision( + request.permission, + todoListConditions.isOwner({ + userId: user?.identity.userEntityRef ?? '', + }), + ); + } + /* highlight-add-end */ + + return { + result: AuthorizeResult.ALLOW, + }; +} ``` For any incoming update requests, we now return a _Conditional Decision_. We are saying: diff --git a/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md b/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md index e84f53f176..4b12e9e407 100644 --- a/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md +++ b/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md @@ -8,21 +8,25 @@ Authorizing `GET /todos` is similar to the update endpoint, in that it should be One possible solution may leverage the batching functionality to authorize all of the todos, and then returning only the ones for which the decision was `ALLOW`: -```diff - router.get('/todos', async (req, res) => { -+ const token = IdentityClient.getBearerToken(req.header('authorization')); +```ts +router.get('/todos', async (req, res) => { + /* highlight-add-next-line */ + const token = IdentityClient.getBearerToken(req.header('authorization')); -- res.json(getAll()) -+ const items = getAll(); -+ const decisions = await permissions.authorize( -+ items.map(({ id }) => ({ permission: todoListReadPermission, resourceRef: id })), -+ ); + /* highlight-remove-next-line */ + res.json(getAll()) + /* highlight-add-start */ + const items = getAll(); + const decisions = await permissions.authorize( + items.map(({ id }) => ({ permission: todoListReadPermission, resourceRef: id })), + ); -+ const filteredItems = decisions.filter( -+ decision => decision.result === AuthorizeResult.ALLOW, -+ ); -+ res.json(filteredItems); - }); + const filteredItems = decisions.filter( + decision => decision.result === AuthorizeResult.ALLOW, + ); + res.json(filteredItems); + /* highlight-add-end */ +}); ``` This approach will work for simple cases, but it has a downside: it forces us to retrieve all the elements upfront and authorize them one by one. This forces the plugin implementation to handle concerns like pagination, which is currently handled by the data source. @@ -35,82 +39,93 @@ To avoid this situation, the permissions framework has support for filtering ite Let's add another permission to the plugin. -```diff - // plugins/todo-list-backend/src/service/permissions.ts +```ts title="plugins/todo-list-backend/src/service/permissions.ts" +import { createPermission } from '@backstage/plugin-permission-common'; - import { createPermission } from '@backstage/plugin-permission-common'; +export const TODO_LIST_RESOURCE_TYPE = 'todo-item'; - export const TODO_LIST_RESOURCE_TYPE = 'todo-item'; +export const todoListCreatePermission = createPermission({ + name: 'todo.list.create', + attributes: { action: 'create' }, +}); - export const todoListCreatePermission = createPermission({ - name: 'todo.list.create', - attributes: { action: 'create' }, - }); +export const todoListUpdatePermission = createPermission({ + name: 'todo.list.update', + attributes: { action: 'update' }, + resourceType: TODO_LIST_RESOURCE_TYPE, +}); - export const todoListUpdatePermission = createPermission({ - name: 'todo.list.update', - attributes: { action: 'update' }, - resourceType: TODO_LIST_RESOURCE_TYPE, - }); -+ -+ export const todoListReadPermission = createPermission({ -+ name: 'todos.list.read', -+ attributes: { action: 'read' }, -+ resourceType: TODO_LIST_RESOURCE_TYPE, -+ }); +/* highlight-add-start */ +export const todoListReadPermission = createPermission({ + name: 'todos.list.read', + attributes: { action: 'read' }, + resourceType: TODO_LIST_RESOURCE_TYPE, +}); +/* highlight-add-end */ -- export const todoListPermissions = [todoListCreatePermission, todoListUpdatePermission]; -+ export const todoListPermissions = [todoListCreatePermission, todoListUpdatePermission, todoListReadPermission]; +/* highlight-add-next-line */ +export const todoListPermissions = [todoListCreatePermission, todoListUpdatePermission]; +/* highlight-add-next-line */ +export const todoListPermissions = [todoListCreatePermission, todoListUpdatePermission, todoListReadPermission]; ``` ## Using conditional policy decisions So far we've only used the `PermissionEvaluator.authorize` method, which will evaluate conditional decisions before returning a result. In this step, we want to evaluate conditional decisions within our plugin, so we'll use `PermissionEvaluator.authorizeConditional` instead. -```diff -// plugins/todo-list-backend/src/service/router.ts +```ts title="plugins/todo-list-backend/src/service/router.ts" +/* highlight-remove-next-line */ +import { createPermissionIntegrationRouter } from '@backstage/plugin-permission-node'; +/* highlight-add-start */ +import { + createPermissionIntegrationRouter, + createConditionTransformer, + ConditionTransformer, +} from '@backstage/plugin-permission-node'; +/* highlight-add-end */ +/* highlight-remove-next-line */ +import { add, getAll, getTodo, update } from './todos'; +/* highlight-add-next-line */ +import { add, getAll, getTodo, TodoFilter, update } from './todos'; +import { + todosListCreate, + todosListUpdate, + /* highlight-add-next-line */ + todoListReadPermission, + TODO_LIST_RESOURCE_TYPE, +} from './permissions'; -- import { createPermissionIntegrationRouter } from '@backstage/plugin-permission-node'; -+ import { -+ createPermissionIntegrationRouter, -+ createConditionTransformer, -+ ConditionTransformer, -+ } from '@backstage/plugin-permission-node'; -- import { add, getAll, getTodo, update } from './todos'; -+ import { add, getAll, getTodo, TodoFilter, update } from './todos'; - import { - todosListCreate, - todosListUpdate, -+ todoListReadPermission, - TODO_LIST_RESOURCE_TYPE, - } from './permissions'; +/* highlight-add-next-line */ +const transformConditions: ConditionTransformer = createConditionTransformer(Object.values(rules)); -+ const transformConditions: ConditionTransformer = createConditionTransformer(Object.values(rules)); +/* highlight-remove-next-line */ +router.get('/todos', async (_req, res) => { +/* highlight-add-start */ +router.get('/todos', async (req, res) => { + const token = getBearerTokenFromAuthorizationHeader( + req.header('authorization'), + ); -- router.get('/todos', async (_req, res) => { -+ router.get('/todos', async (req, res) => { -+ const token = getBearerTokenFromAuthorizationHeader( -+ req.header('authorization'), -+ ); -+ -+ const decision = ( -+ await permissions.authorizeConditional([{ permission: todoListReadPermission }], { -+ token, -+ }) -+ )[0]; -+ -+ if (decision.result === AuthorizeResult.DENY) { -+ throw new NotAllowedError('Unauthorized'); -+ } -+ -+ if (decision.result === AuthorizeResult.CONDITIONAL) { -+ const filter = transformConditions(decision.conditions); -+ res.json(getAll(filter)); -+ } else { -+ res.json(getAll()); -+ } -- res.json(getAll()); - }); + const decision = ( + await permissions.authorizeConditional([{ permission: todoListReadPermission }], { + token, + }) + )[0]; + + if (decision.result === AuthorizeResult.DENY) { + throw new NotAllowedError('Unauthorized'); + } + + if (decision.result === AuthorizeResult.CONDITIONAL) { + const filter = transformConditions(decision.conditions); + res.json(getAll(filter)); + } else { + res.json(getAll()); + } +/* highlight-add-end */ + /* highlight-remove-next-line */ + res.json(getAll()); +}); ``` To make the process of handling conditional decisions easier, the permission framework provides a `createConditionTransformer` helper. This function accepts an array of permission rules, and returns a transformer function which converts the conditions to the format needed by the plugin using the `toQuery` method defined on each rule. @@ -121,31 +136,29 @@ Since `TodoFilter` used in our plugin matches the structure of the conditions ob Let's update our permission policy to return a conditional result whenever a `todoListReadPermission` permission is received. In this case, we can reuse the decision returned for the `todosListCreate` permission. -```diff -// packages/backend/src/plugins/permission.ts - -... - +```ts title="packages/backend/src/plugins/permission.ts" import { todoListCreatePermission, todoListUpdatePermission, -+ todoListReadPermission, + /* highlight-add-next-line */ + todoListReadPermission, } from '@internal/plugin-todo-list-common'; -... - -- if (isPermission(request.permission, todoListUpdatePermission)) { -+ if ( -+ isPermission(request.permission, todoListUpdatePermission) || -+ isPermission(request.permission, todoListReadPermission) -+ ) { - return createTodoListConditionalDecision( - request.permission, - todoListConditions.isOwner({ - userId: user?.identity.userEntityRef - }), - ); - } +/* highlight-remove-next-line */ +if (isPermission(request.permission, todoListUpdatePermission)) { +/* highlight-add-start */ +if ( + isPermission(request.permission, todoListUpdatePermission) || + isPermission(request.permission, todoListReadPermission) +) { +/* highlight-add-end */ + return createTodoListConditionalDecision( + request.permission, + todoListConditions.isOwner({ + userId: user?.identity.userEntityRef + }), + ); +} ``` Once the changes to the permission policy are saved, the UI should show only the todo items you've created. diff --git a/docs/permissions/plugin-authors/05-frontend-authorization.md b/docs/permissions/plugin-authors/05-frontend-authorization.md index 753ce56461..235495e13f 100644 --- a/docs/permissions/plugin-authors/05-frontend-authorization.md +++ b/docs/permissions/plugin-authors/05-frontend-authorization.md @@ -14,81 +14,79 @@ Take, for example, the "Add" button in our todo list application. When a user cl Let's start by adding the packages we will need: -``` +```bash $ yarn workspace @internal/plugin-todo-list \ add @backstage/plugin-permission-react @internal/plugin-todo-list-common ``` Let's make the following changes in `plugins/todo-list/src/components/TodoListPage/TodoListPage.tsx`: -```diff -... +```tsx title="plugins/todo-list/src/components/TodoListPage/TodoListPage.tsx" +import { + alertApiRef, + discoveryApiRef, + fetchApiRef, + useApi, +} from '@backstage/core-plugin-api'; +/* highlight-add-start */ +import { usePermission } from '@backstage/plugin-permission-react'; +import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +/* highlight-add-end */ - import { - alertApiRef, - discoveryApiRef, - fetchApiRef, - useApi, - } from '@backstage/core-plugin-api'; -+ import { usePermission } from '@backstage/plugin-permission-react'; -+ import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +function AddTodo({ onAdd }: { onAdd: (title: string) => any }) { + const title = useRef(''); + /* highlight-add-next-line */ + const { loading: loadingPermission, allowed: canAddTodo } = usePermission({ permission: todoListCreatePermission }); -... - - function AddTodo({ onAdd }: { onAdd: (title: string) => any }) { - const title = useRef(''); -+ const { loading: loadingPermission, allowed: canAddTodo } = usePermission({ permission: todoListCreatePermission }); - - return ( - <> - Add todo - - (title.current = e.target.value)} - /> -- -+ {!loadingPermission && ( -+ -+ )} - - - ); - } - -... + return ( + <> + Add todo + + (title.current = e.target.value)} + /> + {/* highlight-remove-start */} + + {/* highlight-remove-end */} + {/* highlight-add-start */} + {!loadingPermission && ( + + )} + {/* highlight-add-end */} + + + ); +} ``` Here we are using the [`usePermission` hook](https://backstage.io/docs/reference/plugin-permission-react.usepermission) to communicate with the permission policy and receive a decision on whether this user is authorized to create a todo list item. It's really that simple! Let's change our policy to test the disabled button: -```diff -// packages/backend/src/plugins/permission.ts +```ts title="packages/backend/src/plugins/permission.ts" -... - - if (isPermission(request.permission, todoListCreatePermission)) { - return { -- result: AuthorizeResult.ALLOW, -+ result: AuthorizeResult.DENY, - }; - } - -... +if (isPermission(request.permission, todoListCreatePermission)) { + return { + /* highlight-remove-next-line */ + result: AuthorizeResult.ALLOW, + /* highlight-add-next-line */ + result: AuthorizeResult.DENY, + }; +} ``` And now you should see that you are not able to create a todo item from the frontend! @@ -97,104 +95,111 @@ And now you should see that you are not able to create a todo item from the fron Providing a disabled state can be a helpful signal to users, but there may be cases where hiding the element is preferred. For such cases, you can use the provided [`RequirePermission` component](https://backstage.io/docs/reference/plugin-permission-react.requirepermission): -```diff -// plugins/todo-list/src/components/TodoListPage/TodoListPage.tsx +```tsx title="plugins/todo-list/src/components/TodoListPage/TodoListPage.tsx" +import { + alertApiRef, + discoveryApiRef, + fetchApiRef, + useApi, +} from '@backstage/core-plugin-api'; +/* highlight-remove-next-line */ +import { usePermission } from '@backstage/plugin-permission-react'; +/* highlight-add-next-line */ +import { RequirePermission } from '@backstage/plugin-permission-react'; +import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; -... +export const TodoListPage = () => { + // .. + + {/* highlight-remove-start */} + + + + {/* highlight-remove-end */} + {/* highlight-add-start */} + } + > + + + + + {/* highlight-add-end */} + + + + +} - import { - alertApiRef, - discoveryApiRef, - fetchApiRef, - useApi, - } from '@backstage/core-plugin-api'; -- import { usePermission } from '@backstage/plugin-permission-react'; -+ import { RequirePermission } from '@backstage/plugin-permission-react'; - import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +function AddTodo({ onAdd }: { onAdd: (title: string) => any }) { + const title = useRef(''); + /* highlight-remove-next-line */ + const { loading: loadingPermission, allowed: canAddTodo } = usePermission({ permission: todoListCreatePermission }); -... - - export const TodoListPage = () => { - -... - - -- -- -- -+ } -+ > -+ -+ -+ -+ - - - - - -... - - - function AddTodo({ onAdd }: { onAdd: (title: string) => any }) { - const title = useRef(''); -- const { loading: loadingPermission, allowed: canAddTodo } = usePermission({ permission: todoListCreatePermission }); - - return ( - <> - Add todo - - (title.current = e.target.value)} - /> -- {!loadingPermission && ( -- -- )} -+ - - - ); - } - -... + return ( + <> + Add todo + + (title.current = e.target.value)} + /> + {/* highlight-remove-start */} + {!loadingPermission && ( + + )} + {/* highlight-remove-end */} + {/* highlight-add-start */} + + {/* highlight-add-end */} + + + ); +} ``` Now you should find that the component for adding a todo list item does not render at all. Success! You can also use `RequirePermission` to prevent access to routes as well. Here's how that would look in your `packages/app/src/App.tsx`: -```diff -+ import { RequirePermission } from '@backstage/plugin-permission-react'; -+ import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; - -... +```tsx title="packages/app/src/App.tsx" +/* highlight-add-start */ +import { RequirePermission } from '@backstage/plugin-permission-react'; +import { todoListCreatePermission } from '@internal/plugin-todo-list-common'; +/* highlight-add-end */ +const routes = ( + }> {searchPage} } /> -+ -+ -+ + {/* highlight-add-next-line */} + + + + {/* highlight-add-end */}} + {/* ... */} + +); ``` Now if you try to navigate to `https://localhost:3000/todo-list` you'll get and error page if you do not have permission. diff --git a/docs/permissions/writing-a-policy.md b/docs/permissions/writing-a-policy.md index 7e741ae48f..3d4371f038 100644 --- a/docs/permissions/writing-a-policy.md +++ b/docs/permissions/writing-a-policy.md @@ -8,9 +8,7 @@ In the [previous section](./getting-started.md), we were able to set up the perm That policy looked like this: -```typescript -// packages/backend/src/plugins/permission.ts - +```typescript title="packages/backend/src/plugins/permission.ts" class TestPermissionPolicy implements PermissionPolicy { async handle(request: PolicyQuery): Promise { if (request.permission.name === 'catalog.entity.delete') { @@ -36,49 +34,61 @@ As we confirmed in the previous section, we know that this now prevents us from Let's change the policy to the following: -```diff -- import { IdentityClient } from '@backstage/plugin-auth-node'; -+ import { -+ BackstageIdentityResponse, -+ IdentityClient -+ } from '@backstage/plugin-auth-node'; - import { +```ts +/* highlight-remove-next-line */ +import { IdentityClient } from '@backstage/plugin-auth-node'; +/* highlight-add-start */ +import { + BackstageIdentityResponse, + IdentityClient +} from '@backstage/plugin-auth-node'; + /* highlight-add-end */ +import { AuthorizeResult, PolicyDecision, -+ isPermission, + /* highlight-add-next-line */ + isPermission, } from '@backstage/plugin-permission-common'; -+ import { -+ catalogConditions, -+ createCatalogConditionalDecision, -+ } from '@backstage/plugin-catalog-backend/alpha'; -+ import { -+ catalogEntityDeletePermission, -+ } from '@backstage/plugin-catalog-common/alpha'; +/* highlight-add-start */ +import { + catalogConditions, + createCatalogConditionalDecision, +} from '@backstage/plugin-catalog-backend/alpha'; +import { + catalogEntityDeletePermission, +} from '@backstage/plugin-catalog-common/alpha'; +/* highlight-add-end */ - ... - - class TestPermissionPolicy implements PermissionPolicy { -- async handle(request: PolicyQuery): Promise { -+ async handle( -+ request: PolicyQuery, -+ user?: BackstageIdentityResponse, -+ ): Promise { -- if (request.permission.name === 'catalog.entity.delete') { -+ if (isPermission(request.permission, catalogEntityDeletePermission)) { -- return { -- result: AuthorizeResult.DENY, -- }; -+ return createCatalogConditionalDecision( -+ request.permission, -+ catalogConditions.isEntityOwner({ -+ claims: user?.identity.ownershipEntityRefs ?? [], -+ }), -+ ); - } - - return { result: AuthorizeResult.ALLOW }; +class TestPermissionPolicy implements PermissionPolicy { + /* highlight-remove-next-line */ + async handle(request: PolicyQuery): Promise { + /* highlight-add-start */ + async handle( + request: PolicyQuery, + user?: BackstageIdentityResponse, + ): Promise { + /* highlight-add-end */ + /* highlight-remove-next-line */ + if (request.permission.name === 'catalog.entity.delete') { + /* highlight-add-next-line */ + if (isPermission(request.permission, catalogEntityDeletePermission)) { + /* highlight-remove-start */ + return { + result: AuthorizeResult.DENY, + }; + /* highlight-remove-end */ + /* highlight-add-start */ + return createCatalogConditionalDecision( + request.permission, + catalogConditions.isEntityOwner({ + claims: user?.identity.ownershipEntityRefs ?? [], + }), + ); + /* highlight-add-end */ } + return { result: AuthorizeResult.ALLOW }; } +} ``` Let's walk through the new code that we just added. @@ -93,30 +103,34 @@ You should now be able to see in your Backstage app that the unregister entity b Now let's say we want to prevent all actions on catalog entities unless performed by the owner. One way to achieve this may be to simply update the `if` statement and check for each permission. If you choose to write your policy this way, it will certainly work! However, it may be difficult to maintain as the policy grows, and it may not be obvious if certain permissions are left out. We can author this same policy in a more scalable way by checking the resource type of the requested permission. -```diff +```ts import { AuthorizeResult, PolicyDecision, -- isPermission, -+ isResourcePermission, + /* highlight-remove-next-line */ + isPermission, + isResourcePermission, + /* highlight-add-next-line */ } from '@backstage/plugin-permission-common'; - import { - catalogConditions, - createCatalogConditionalDecision, - } from '@backstage/plugin-catalog-backend/alpha'; -- import { -- catalogEntityDeletePermission, -- } from '@backstage/plugin-catalog-common/alpha'; - -... +import { + catalogConditions, + createCatalogConditionalDecision, +} from '@backstage/plugin-catalog-backend/alpha'; +/* highlight-remove-start */ +import { + catalogEntityDeletePermission, +} from '@backstage/plugin-catalog-common/alpha'; +/* highlight-remove-end */ class TestPermissionPolicy implements PermissionPolicy { async handle( request: PolicyQuery, user?: BackstageIdentityResponse, ): Promise { -- if (isPermission(request.permission, catalogEntityDeletePermission)) { -+ if (isResourcePermission(request.permission, 'catalog-entity')) { + /* highlight-remove-next-line */ + if (isPermission(request.permission, catalogEntityDeletePermission)) { + /* highlight-add-next-line */ + if (isResourcePermission(request.permission, 'catalog-entity')) { return createCatalogConditionalDecision( request.permission, catalogConditions.isEntityOwner({ @@ -127,6 +141,7 @@ class TestPermissionPolicy implements PermissionPolicy { return { result: AuthorizeResult.ALLOW }; } +} ``` In this example, we use [`isResourcePermission`](https://backstage.io/docs/reference/plugin-permission-common.isresourcepermission) to match all permissions with a resource type of `catalog-entity`. Just like `isPermission`, this helper will "narrow" the type of `request.permission` and enable the use of `createCatalogConditionalDecision`. In addition to the behavior you observed before, you should also see that catalog entities are no longer visible unless you are the owner - success! diff --git a/docs/tutorials/migrating-away-from-core.md b/docs/tutorials/migrating-away-from-core.md index da9d177ccb..32f9dc5ad0 100644 --- a/docs/tutorials/migrating-away-from-core.md +++ b/docs/tutorials/migrating-away-from-core.md @@ -38,10 +38,13 @@ across your project. This will automatically convert all module imports in your source code to use one of the three new core packages instead. For example, the following change might occur: -```diff --import { useApi, configApiRef, InfoCard } from '@backstage/core'; -+import { useApi, configApiRef } from '@backstage/core-plugin-api'; -+import { InfoCard } from '@backstage/core-components'; +```ts +/* highlight-remove-next-line */ +import { useApi, configApiRef, InfoCard } from '@backstage/core'; +/* highlight-add-start */ +import { useApi, configApiRef } from '@backstage/core-plugin-api'; +import { InfoCard } from '@backstage/core-components'; +/* highlight-add-end */ ``` In a typical app created with `@backstage/create-app`, you would run the diff --git a/docs/tutorials/react-router-stable-migration.md b/docs/tutorials/react-router-stable-migration.md index bb01157bdb..24dba3c244 100644 --- a/docs/tutorials/react-router-stable-migration.md +++ b/docs/tutorials/react-router-stable-migration.md @@ -45,7 +45,7 @@ yarn backstage-cli migrate react-router-deps For those interested in doing this manually, apply the below change to all `package.json` files except the one at `packages/app/package.json` or any other app packages. Skip moving any dependencies that don't already exist, and move both `dependencies` and `devDependencies`. -```diff +```diff title="package.json" dependencies { ... - "react-router-dom": "^6.0.0-beta.0", @@ -64,13 +64,13 @@ It's important that you also update your external plugins to their latest versio During this migration there may be external plugins that need updating. If you encounter any plugins outside of the `@backstage` scope that are incompatible with your installation, make sure to check for an existing issue or raise a new one at the plugin's GitHub repository. -### Step 4 - Bump the React Router dependencies in your app. +### Step 4 - Bump the React Router dependencies in your app Now it's time to do the actual migration to the latest version of React Router. At this time of writing that is `6.3.0`, but that is of course a moving target. The first step is to modify `packages/app/package.json`: -```diff +```diff title="package.json" - "react-router": "6.0.0-beta.0", - "react-router-dom": "6.0.0-beta.0", + "react-router": "^6.3.0", @@ -81,7 +81,7 @@ In case you happen to have multiple app packages in your project, apply the same Once the change has been made, run `yarn install`, and then `yarn why react-router` to validate the installation. You should see the following line in the log as the only resulting entry: -``` +```bash => Found "react-router@6.3.0" ``` @@ -157,28 +157,34 @@ Because of the above change, the `PermissionedRoute` component no longer works i It's crucial that you update to `RequirePermission` at the same time as you update to React Router v6 stable as the `PermissionedRoute` component will no longer function. -```diff -- } -+ -+ -+ -+ } - /> +```tsx +{/* highlight-remove-start */} +} +{/* highlight-remove-end */} +{/* highlight-add-start */} + + + + } +{/* highlight-add-end */} +/> ``` ### `` component When migrating over to React Router v6 stable, you might also see browser console warnings for the `Navigate` component. This will need to be wrapped up in a `Route` component with the `Navigate` component in the `element` prop. -```diff -- -+ } /> +```tsx +{/* highlight-remove-next-line */} + +{/* highlight-add-next-line */} +} /> ``` ### `NavLink` diff --git a/docs/tutorials/switching-sqlite-postgres.md b/docs/tutorials/switching-sqlite-postgres.md index bd067ee388..b87a77f4ed 100644 --- a/docs/tutorials/switching-sqlite-postgres.md +++ b/docs/tutorials/switching-sqlite-postgres.md @@ -29,24 +29,28 @@ yarn add --cwd packages/backend pg Next, modify `app-config.yaml` in the root folder to add PostgreSQL configuration for the backend: -```diff +```yaml title="app-config.yaml" backend: database: -- client: better-sqlite3 -- connection: ':memory:' -+ # config options: https://node-postgres.com/api/client -+ client: pg -+ connection: -+ host: ${POSTGRES_HOST} -+ port: ${POSTGRES_PORT} -+ user: ${POSTGRES_USER} -+ password: ${POSTGRES_PASSWORD} -+ # https://node-postgres.com/features/ssl -+ # you can set the sslmode configuration option via the `PGSSLMODE` environment variable -+ # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) -+ # ssl: -+ # ca: # if you have a CA file and want to verify it you can uncomment this section -+ # $file: /ca/server.crt + # highlight-remove-start + client: better-sqlite3 + connection: ':memory:' + # highlight-remove-end + # highlight-add-start + # config options: https://node-postgres.com/api/client + client: pg + connection: + host: ${POSTGRES_HOST} + port: ${POSTGRES_PORT} + user: ${POSTGRES_USER} + password: ${POSTGRES_PASSWORD} + # https://node-postgres.com/features/ssl + # you can set the sslmode configuration option via the `PGSSLMODE` environment variable + # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) + # ssl: + # ca: # if you have a CA file and want to verify it you can uncomment this section + # $file: /ca/server.crt + # highlight-add-end ``` If you have an `app-config.local.yaml` for local development, a similar update @@ -60,31 +64,35 @@ The Backstage App is now ready to start up with a PostgreSQL backing database. If you want to override the default connection pool settings then use the below configuration: -```diff +```yaml title="app-config.local.yaml" backend: database: -- client: better-sqlite3 -- connection: ':memory:' -+ # config options: https://node-postgres.com/api/client -+ client: pg -+ connection: -+ host: ${POSTGRES_HOST} -+ port: ${POSTGRES_PORT} -+ user: ${POSTGRES_USER} -+ password: ${POSTGRES_PASSWORD} -+ # https://node-postgres.com/features/ssl -+ # you can set the sslmode configuration option via the `PGSSLMODE` environment variable -+ # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) -+ # ssl: -+ # ca: # if you have a CA file and want to verify it you can uncomment this section -+ # $file: /ca/server.crt -+ # Refer to Tarn docs for default values on PostgreSQL pool configuration - https://github.com/Vincit/tarn.js -+ knexConfig: -+ pool: -+ min: 3 -+ max: 12 -+ acquireTimeoutMillis: 60000 -+ idleTimeoutMillis: 60000 + # highlight-remove-start + client: better-sqlite3 + connection: ':memory:' + # highlight-remove-end + # highlight-add-start + # config options: https://node-postgres.com/api/client + client: pg + connection: + host: ${POSTGRES_HOST} + port: ${POSTGRES_PORT} + user: ${POSTGRES_USER} + password: ${POSTGRES_PASSWORD} + # https://node-postgres.com/features/ssl + # you can set the sslmode configuration option via the `PGSSLMODE` environment variable + # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) + # ssl: + # ca: # if you have a CA file and want to verify it you can uncomment this section + # $file: /ca/server.crt + # Refer to Tarn docs for default values on PostgreSQL pool configuration - https://github.com/Vincit/tarn.js + knexConfig: + pool: + min: 3 + max: 12 + acquireTimeoutMillis: 60000 + idleTimeoutMillis: 60000 + # highlight-add-end ``` ### Using a single database diff --git a/docs/tutorials/yarn-migration.md b/docs/tutorials/yarn-migration.md index 6dee343e78..9e041a5969 100644 --- a/docs/tutorials/yarn-migration.md +++ b/docs/tutorials/yarn-migration.md @@ -82,19 +82,24 @@ RUN yarn workspaces focus --all --production && rm -rf "$(yarn cache clean)" Additionally, `yarn config` has been reworked from being able to store any arbitrary key-value pairs to only supporting a handful of predefined pairs. Previously, we would set our preferred `python3` interpreter to work around [any issues related to node-gyp](https://github.com/backstage/backstage/issues/11583) so we need to provide an appropriate substitute. -```diff +```Dockerfile FROM node:16-bullseye-slim -+# Set Python interpreter for `node-gyp` to use -+ENV PYTHON /usr/bin/python3 +# highlight-add-start +# Set Python interpreter for `node-gyp` to use +ENV PYTHON /usr/bin/python3 +# highlight-add-end # Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image, # in which case you should also move better-sqlite3 to "devDependencies" in package.json. RUN apt-get update && \ apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \ -- rm -rf /var/lib/apt/lists/* && \ -- yarn config set python /usr/bin/python3 -+ rm -rf /var/lib/apt/lists/* + # highlight-remove-start + rm -rf /var/lib/apt/lists/* && \ + yarn config set python /usr/bin/python3 + # highlight-remove-end + # highlight-add-next-line + rm -rf /var/lib/apt/lists/* ``` You'll want to make sure that the `PYTHON` environment variable is declared relatively early, before any instances of `Yarn` are invoked as `node-gyp` is indirectly triggered by some modules during installation. diff --git a/microsite-next/docusaurus.config.js b/microsite-next/docusaurus.config.js index b3d1d16af1..b07700fb0e 100644 --- a/microsite-next/docusaurus.config.js +++ b/microsite-next/docusaurus.config.js @@ -249,5 +249,28 @@ module.exports = { appId: 'JCMFNHCHI8', searchParameters: {}, }, + prism: { + magicComments: [ + // Extend the default highlight class name + { + className: 'theme-code-block-highlighted-line', + line: 'highlight-next-line', + block: { start: 'highlight-start', end: 'highlight-end' }, + }, + { + className: 'code-block-add-line', + line: 'highlight-add-next-line', + block: { start: 'highlight-add-start', end: 'highlight-add-end' }, + }, + { + className: 'code-block-remove-line', + line: 'highlight-remove-next-line', + block: { + start: 'highlight-remove-start', + end: 'highlight-remove-end', + }, + }, + ], + }, }, }; diff --git a/microsite-next/src/css/customTheme.css b/microsite-next/src/css/customTheme.css index 1a39467516..4ba7f1df86 100644 --- a/microsite-next/src/css/customTheme.css +++ b/microsite-next/src/css/customTheme.css @@ -56,3 +56,23 @@ ); } /* #endregion */ + +/* prism magic comments https://docusaurus.io/docs/markdown-features/code-blocks#custom-magic-comments */ + +.code-block-add-line { + background-color: rgba(0, 255, 0, 0.125); + display: block; + margin: 0 calc(-1 * var(--ifm-pre-padding)); + padding: 0 var(--ifm-pre-padding); + border-left: 3px solid rgba(0, 255, 0, 0.5); +} + +.code-block-remove-line { + background-color: rgba(255, 0, 0, 0.125); + display: block; + margin: 0 calc(-1 * var(--ifm-pre-padding)); + padding: 0 var(--ifm-pre-padding); + border-left: 3px solid rgba(255, 0, 0, 0.5); +} + +/* #endregion */