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

Merge branch 'backstage:master' into feature/asyncapi3

Browse Source
This commit is contained in:
Fabrizio Lazzaretti
2024-02-08 10:24:03 +01:00
committed by GitHub
parent 00709f574e 8b5ac7a925
commit a6620fbc5a
1405 changed files with 33261 additions and 6583 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auth/glossary.md
-30
View File
@@ -1,30 +0,0 @@
---
id: glossary
title: Glossary
description: All Glossaries related to auth
---
- **Popup** - A separate browser window opened on top of the previous one.
- **OAuth** - More specifically OAuth 2.0, a standard protocol for
authorization. See [oauth.net/2/](https://oauth.net/2/).
- **OpenID Connect** - A layer on top of OAuth which standardises
authentication. See
[en.wikipedia.org/wiki/OpenID_Connect](https://en.wikipedia.org/wiki/OpenID_Connect).
- **JWT** - JSON Web Token, a popular JSON based token format that is commonly
encrypted and/or signed, see
[en.wikipedia.org/wiki/JSON_Web_Token](https://en.wikipedia.org/wiki/JSON_Web_Token)
- **Scope** - A string that describes a certain type of access that can be
granted to a user using OAuth.
- **Access token** - A token that gives access to perform actions on behalf of a
user. It will commonly have a short expiry time, and be limited to a set of
scopes. Part of the OAuth protocol.
- **ID token** - A JWT used to prove a user's identity, containing for example
the user's email. Part of OpenID Connect.
- **Offline access** - OAuth flow that results in both a refresh and access
token, where the refresh token has a long expiration or never expires, and can
be used to request more access tokens in the future. This lets the user go
"offline" with respect to the token issuer, but still be able to request more
tokens at a later time without further direct interaction for the user.
- **Code grant** - OAuth flow where the client receives an authorization code
that is passed to the backend to be exchanged for an access token and possibly
refresh token.
docs/auth/index.md
+1
View File
@@ -35,6 +35,7 @@ Backstage comes with many common authentication providers in the core library:
- [Okta](okta/provider.md)
- [OAuth 2 Custom Proxy](oauth2-proxy/provider.md)
- [OneLogin](onelogin/provider.md)
- [VMware Cloud](vmware-cloud/provider.md)
These built-in providers handle the authentication flow for a particular service
including required scopes, callbacks, etc. These providers are each added to a
docs/auth/vmware-cloud/provider.md
+171
View File
@@ -0,0 +1,171 @@
---
id: provider
title: VMware Cloud Authentication Provider
sidebar_label: VMware Cloud
description: Adding VMware Cloud as an authentication provider in Backstage
---
Backstage comes with an auth provider module to allow users to sign-in with
their VMware Cloud account. This page describes some actions within the VMware
Cloud Console and within a Backstage app required to enable this capability.
## Create an OAuth App in the VMware Cloud Console
1. Log in to the [VMware Cloud Console](https://console.cloud.vmware.com).
1. Navigate to [Identity & Access Management > OAuth
Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps)
and click the [Owned
Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps/owned-apps/view)
tab -- if you are not an Organization Owner or Administrator but only a
Member, you will not see this nav entry unless the **Developer** check box is
selected for your role (see the [Organization roles and
permissions](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html#organization-roles-and-permissions-0)
docs for details).
1. Click **Create App**, choose 'Web/Mobile app' and click **Continue**.
1. Use default settings except:
- `App Name` and `App Description` of your choosing.
- `Redirect URIs`: `${baseUrl}/api/auth/vmwareCloudServices/handler/frame`
where `baseUrl` is the URL where your Backstage backend can be reached;
note that VMware Cloud does not support the combination of an `http://`
scheme and a `localhost` hostname, so when testing locally it may help to
set your backend base URL to `http://127.0.0.1:7007`.
- `Refresh Token`: check `Issue refresh token`; refresh tokens are required
to prevent forcing users to re-login when they refresh their browser.
- `Define Scopes`: check `OpenID` at the bottom.
1. Click **Create**.
1. Take note of the `App ID` in the resulting modal; this is the client ID to be
used by Backstage.
## Install the provider in the backend
### New backend system
Apps using the [new backend system](../../backend-system/index.md),
can enable the VMware Cloud provider with a small modification like:
```ts title="packages/backend-next/src/index.ts"
import { createBackend } from '@backstage/backend-defaults';
const backend = createBackend();
backend.add(import('@backstage/plugin-auth-backend'));
/* highlight-add-start */
backend.add(
import('@backstage/plugin-auth-backend-module-vmware-cloud-provider'),
);
/* highlight-add-end */
backend.start();
```
### Old backend system
This provider was added after the migration of the auth-backend plugin to the
new backend system, so no default provider factory was added. Because of this,
the installation procedure for old-style backends is slightly more involved:
```ts title="packages/backend/src/plugins/auth.ts"
import {
DEFAULT_NAMESPACE,
stringifyEntityRef,
} from '@backstage/catalog-model';
import {
createRouter,
providers,
defaultAuthProviderFactories,
} from '@backstage/plugin-auth-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
/* highlight-add-start */
import {
commonSignInResolvers,
createOAuthProviderFactory,
} from '@backstage/plugin-auth-node';
import {
vmwareCloudAuthenticator,
} from '@backstage/plugin-auth-backend-module-vmware-cloud-provider';
/* highlight-add-end */
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
logger: env.logger,
config: env.config,
database: env.database,
discovery: env.discovery,
tokenManager: env.tokenManager,
providerFactories: {
...defaultAuthProviderFactories,
/* highlight-add-start */
vmwareCloudServices: createOAuthProviderFactory({
authenticator: vmwareCloudAuthenticator,
signInResolver:
commonSignInResolvers.emailLocalPartMatchingUserEntityName(),
}),
/* highlight-add-end */
```
In the above, `commonSignInResolvers.emailLocalPartMatchingUserEntityName()`
can be replaced with a more suitable resolver for the app in question.
## Configure Sign-in Resolution
See [Sign-in Identities and Resolvers](../identity-resolver.md) for details.
## Add to Sign-in Page
See the [Sign-In Configuration](../index.md#sign-in-configuration) docs for
general guidance, but as an example:
```tsx title="packages/app/src/App.tsx"
/* highlight-add-start */
import { vmwareCloudAuthApiRef } from '@backstage/core-plugin-api';
import { SignInPage } from '@backstage/core-components';
/* highlight-add-end */
const app = createApp({
/* highlight-add-start */
components: {
SignInPage: props => (
<SignInPage
{...props}
provider={{
id: 'vmware-cloud-auth-provider',
title: 'VMware Cloud',
message: 'Sign in using VMware Cloud',
apiRef: vmwareCloudAuthApiRef,
}}
/>
),
},
/* highlight-add-end */
// ..
});
```
## Configuration
Add the following to your `app-config.yaml` under the root `auth` configuration:
```yaml
auth:
session:
secret: your session secret
environment: development
providers:
vmwareCloudServices:
development:
clientId: ${APP_ID}
organizationId: ${ORG_ID}
```
where `APP_ID` refers to the ID retrieved when creating the OAuth App, and
`ORG_ID` is the [long ID of the
Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1)
in VMware Cloud for which you wish to enable sign-in.
Note that VMware Cloud requires OAuth Apps to use
[PKCE](https://oauth.net/2/pkce/) when performing authorization code flows; the
library used by this provider requires the use of Express session middleware to
do this. Therefore the value `your session secret` under `auth.session.secret`
should be replaced with a long, complex and unique string which will act as a
key for signing session cookies set by Backstage.
docs/backend-system/building-backends/08-migrating.md
+5 -5
View File
@@ -83,7 +83,7 @@ following command:
```bash
# from the repository root
yarn add --cwd packages/backend @backstage/backend-defaults @backstage/backend-plugin-api
yarn --cwd packages/backend add @backstage/backend-defaults @backstage/backend-plugin-api
```
You should now be able to start this up with the familiar `yarn workspace
@@ -616,7 +616,7 @@ if you didn't already have one.
```bash
# from the repository root
yarn add --cwd packages/backend @backstage/plugin-catalog-node
yarn --cwd packages/backend add @backstage/plugin-catalog-node
```
Here we've placed the module directly in the backend index file just to get
@@ -681,7 +681,7 @@ if you didn't already have one.
```bash
# from the repository root
yarn add --cwd packages/backend @backstage/plugin-events-node
yarn --cwd packages/backend add @backstage/plugin-events-node
```
Here we've placed the module directly in the backend index file just to get
@@ -715,7 +715,7 @@ And of course you'll need to install those separately as well.
```bash
# from the repository root
yarn add --cwd packages/backend @backstage/plugin-scaffolder-backend-module-github
yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-github
```
You can find a list of the available modules under the [plugins directory](https://github.com/backstage/backstage/tree/master/plugins) in the monorepo.
@@ -766,7 +766,7 @@ if you didn't already have one.
```bash
# from the repository root
yarn add --cwd packages/backend @backstage/plugin-scaffolder-node
yarn --cwd packages/backend add @backstage/plugin-scaffolder-node
```
Here we've placed the module directly in the backend index file just to get
docs/conf/writing.md
+3 -1
View File
@@ -220,6 +220,8 @@ clientSecret: someGithubAppClientSecret
webhookSecret: someWebhookSecret
privateKey: |
-----BEGIN RSA PRIVATE KEY-----
SomeRsaPrivateKey
SomeRsaPrivateKeySecurelyStored
-----END RSA PRIVATE KEY-----
```
**Warning: Sensitive information, such as private keys, should not be hard coded**. We recommend that this entire file should be a secret and stored as such in a secure storage solution like Vault, to ensure they are neither exposed nor misused. This example key part only shows the format on how to use the yaml | syntax to make sure that the key is valid.
docs/features/kubernetes/installation.md
+2 -2
View File
@@ -17,7 +17,7 @@ application.
```bash
# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-kubernetes
yarn --cwd packages/app add @backstage/plugin-kubernetes
```
Once the package has been installed, you need to import the plugin in your app
@@ -55,7 +55,7 @@ Navigate to `packages/backend` of your Backstage app, and install the
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-kubernetes-backend
yarn --cwd packages/backend add @backstage/plugin-kubernetes-backend
```
Create a file called `kubernetes.ts` inside `packages/backend/src/plugins/` and
docs/features/search/getting-started.md
+2 -2
View File
@@ -18,7 +18,7 @@ If you haven't setup Backstage already, start
```bash
# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-search @backstage/plugin-search-react
yarn --cwd packages/app add @backstage/plugin-search @backstage/plugin-search-react
```
Create a new `packages/app/src/components/search/SearchPage.tsx` file in your
@@ -135,7 +135,7 @@ Add the following plugins into your backend app:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-search-backend @backstage/plugin-search-backend-node
yarn --cwd packages/backend add @backstage/plugin-search-backend @backstage/plugin-search-backend-node
```
Create a `packages/backend/src/plugins/search.ts` file containing the following
docs/features/software-catalog/index.md
+7 -7
View File
@@ -36,7 +36,7 @@ The Software Catalog is available to browse at `/catalog`. If you've followed
[Getting Started with Backstage](../../getting-started), you should be able to
browse the catalog at `http://localhost:3000`.
![](../../assets/software-catalog/software-catalog-home.png)
![screenshot of software catalog](../../assets/software-catalog/software-catalog-home.png)
## Adding components to the catalog
@@ -55,7 +55,7 @@ There are 3 ways to add components to the catalog:
Users can register new components by going to `/create` and clicking the
**REGISTER EXISTING COMPONENT** button:
![](../../assets/software-catalog/bsc-register-1.png)
![screenshot of manually register existing component](../../assets/software-catalog/bsc-register-1.png)
Backstage expects the full URL to the YAML in your source control. Example:
@@ -66,7 +66,7 @@ https://github.com/backstage/backstage/blob/master/packages/catalog-model/exampl
_More examples can be found
[here](https://github.com/backstage/backstage/tree/master/packages/catalog-model/examples)._
![](../../assets/software-catalog/bsc-register-2.png)
![screenshot of creating new components](../../assets/software-catalog/bsc-register-2.png)
It is important to note that any kind of software can be registered in
Backstage. Even if the software is not maintained by your company (SaaS
@@ -100,7 +100,7 @@ More information about catalog configuration can be found
Teams owning the components are responsible for maintaining the metadata about
them, and do so using their normal Git workflow.
![](../../assets/software-catalog/bsc-edit.png)
![screenshot of updating component metadata](../../assets/software-catalog/bsc-edit.png)
Once the change has been merged, Backstage will automatically show the updated
metadata in the software catalog after a short while.
@@ -112,14 +112,14 @@ in user. But you can also switch to _All_ to see all the components across your
company's software ecosystem. Basic inline _search_ and _column filtering_ makes
it easy to browse a big set of components.
![](../../assets/software-catalog/bsc-search.png)
![screenshot of finding software in the catalog](../../assets/software-catalog/bsc-search.png)
## Starring components
For easy and quick access to components you visit frequently, Backstage supports
_starring_ of components:
![](../../assets/software-catalog/bsc-starred.png)
![screenshot of starred components](../../assets/software-catalog/bsc-starred.png)
## Integrated tooling through plugins
@@ -130,7 +130,7 @@ infrastructure UIs (and incurring additional cognitive overhead each time they
make a context switch), most of these tools can be organized around the entities
in the catalog.
![tools](https://backstage.io/assets/images/tabs-abfdf72185d3ceb1d92c4237f7f78809.png)
![screenshot of tools](https://backstage.io/assets/images/tabs-abfdf72185d3ceb1d92c4237f7f78809.png)
The Backstage platform can be customized by incorporating
[existing open source plugins](https://github.com/backstage/backstage/tree/master/plugins),
docs/features/software-templates/writing-templates.md
-29
View File
@@ -274,35 +274,6 @@ spec:
password: ${{ secrets.password }}
```
### Hide or mask sensitive data on Review step
> Note: this approach is soon to be deprecated, please mark things as secret by using the `Secret` field extension instead as mentioned above.
Sometimes, specially in custom fields, you collect some data on Create form that
must not be shown to the user on Review step. To hide or mask this data, you can
use `ui:widget: password` or set some properties of `ui:backstage`:
```yaml
- title: Hide or mask values
properties:
password:
title: Password
type: string
ui:widget: password # will print '******' as value for property 'password' on Review Step
masked:
title: Masked
type: string
ui:backstage:
review:
mask: '<some-value-to-show>' # will print '<some-value-to-show>' as value for property 'Masked' on Review Step
hidden:
title: Hidden
type: string
ui:backstage:
review:
show: false # won't print any info about 'hidden' property on Review Step
```
### Custom step layouts
If you find that the default layout of the form used in a particular step does not meet your needs then you can supply your own [custom step layout](./writing-custom-step-layouts.md).
docs/features/techdocs/addons.md
+1 -1
View File
@@ -54,7 +54,7 @@ Addons are rendered in the order in which they are registered.
## Installing and using Addons
To start using Addons you need to add the `@backstage/plugin-techdocs-module-addons-contrib` package to your app. You can do that by running this command from the root of your project: `yarn add --cwd packages/app @backstage/plugin-techdocs-module-addons-contrib`
To start using Addons you need to add the `@backstage/plugin-techdocs-module-addons-contrib` package to your app. You can do that by running this command from the root of your project: `yarn --cwd packages/app add @backstage/plugin-techdocs-module-addons-contrib`
Addons can be installed and configured in much the same way as extensions for
other Backstage plugins: by adding them underneath an extension registry
docs/features/techdocs/getting-started.md
+2 -2
View File
@@ -23,7 +23,7 @@ Navigate to your new Backstage application directory. And then to your
```bash
# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-techdocs
yarn --cwd packages/app add @backstage/plugin-techdocs
```
Once the package has been installed, you need to import the plugin in your app.
@@ -108,7 +108,7 @@ Navigate to `packages/backend` of your Backstage app, and install the
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-techdocs-backend
yarn --cwd packages/backend add @backstage/plugin-techdocs-backend
```
Create a file called `techdocs.ts` inside `packages/backend/src/plugins/` and
docs/frontend-system/building-apps/01-index.md
+148
View File
@@ -0,0 +1,148 @@
---
id: index
title: Building Frontend Apps
sidebar_label: Overview
# prettier-ignore
description: Building frontend apps using the new frontend system
---
> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
To get set up quickly with your own Backstage project you can create a Backstage App.
A Backstage App is a monorepo setup that includes everything you need to run Backstage in your own environment.
## Creating a new app
To create a new Backstage app we recommend using the `@backstage/create-app` command line, and the easiest way to run this package is with `npx`:
:::note
The create-app CLI requires Node.js Active LTS Release.
:::
```sh
# The command bellow creates a Backstage App inside the current folder.
# The name of the app-folder is the name that was provided when prompted.
npx @backstage/create-app@latest
```
The created-app is currently templated for legacy frontend system applications, so the app wiring code it creates needs to be migrated, see [the app instance](#the-app-instance) section for an example.
## The app instance
The starting point of a frontend app is the `createApp` function, which accepts a single options object as its only parameter. It is imported from `@backstage/frontend-app-api`, which is where you will find most of the common APIs for building apps.
This is how to create a minimal app:
```tsx title="in src/index.ts"
import ReactDOM from 'react-dom/client';
import { createApp } from '@backstage/frontend-app-api';
import catalogPlugin from '@backstage/plugin-catalog/alpha';
// Create your app instance
const app = createApp({
// Features such as plugins can be installed explicitly, but we will explore other options later on
features: [catalogPlugin],
});
// This creates a React element that renders the entire app
const root = app.createRoot();
// Just like any other React we need a root element. No server side rendering is used.
const rootEl = document.getElementById('root')!;
ReactDOM.createRoot(rootEl).render(root);
```
Note that `createRoot` returns the root element that is rendered by React. The above example is installing a catalog plugin and using default settings for the app, as no options other than the `features` array are passed to the `createApp` function.
Visit the [built-in extensions](#customize-or-override-built-in-extensions) section to see what is installed by default in a Backstage application.
## Configure your app
### Bind external routes
Linking routes from different plugins requires this configuration. You can do this either through a configuration file or by coding, visit [this](https://backstage.io/docs/frontend-system/architecture/routes#binding-external-route-references) page for instructions.
### Enable feature discovery
Use this setting to enable experimental feature discovery when building your app with `@backstage/cli`. With this configuration your application tries to discover and install package extensions automatically, check [here](../architecture/02-app.md#feature-discovery) for more details.
:::warning
Remember that package extensions that are not auto-discovered must be manually added to the application when creating an app. See [features](#install-features-manually) for more details.
:::
### Configure extensions individually
It is possible to enable, disable and configure extensions individually in the `app-config.yaml` config file. To get familiar with what is available for app extensions personalization, go to the [built-in extensions](./02-built-in-extensions.md) documentation. For plugin customizations, we recommend that you read the instructions in each plugin's README file.
### Customize or override built-in extensions
Previously you would customize the application route, components, apis, sidebar, etc. through the code in `App.tsx`. Now we want you to write less code and install more extensions to customize your Backstage instance. See [here](../building-plugins/03-extension-types.md) which types of extensions are available for you to customize your application.
## Use code to customize the app at a more granular level
### Install features manually
A manual installation is required if your packages are not discovered automatically, either because you are not using `@backstage/cli` to build your application or because the features are defined in local modules in the app package. In order to manually install a feature, you must import it and pass it to the `createApp` function:
```tsx title="packages/app/src/App.tsx"
import { createApp } from '@backstage/frontend-app-api';
// This plugin was create as a local module in the app
import { somePlugin } from './plugins';
const app = createApp({
features: [somePlugin],
});
export default app.createRoot();
```
:::info
You can also pass overrides to the features array, for more details, please read the [extension overrides](../architecture/05-extension-overrides.md) documentation.
:::
### Using an async features loader
In case you need to perform asynchronous operations before passing features to the `createApp` function, define a [feature loader](https://backstage.io/docs/reference/frontend-app-api.createappfeatureloader/) object and pass it to the `features` option:
```tsx title="packages/app/src/App.tsx"
import { createApp } from '@backstage/frontend-app-api';
const app = createApp({
features: {
getLoaderName: () => '<your-custom-features-loader-name>',
// there is a reference to the config api in the options param
load: async _options => {
// returning a lazy loaded plugins and overrides array
// could be util for module federation
return import('./features').then(m => m.default);
},
},
});
export default app.createRoot();
```
### Lazy load your configuration file
In some cases we want to load our configuration from a backend server and to do so, you can pass an callback to the `configLoader` option when calling the `createApp` function, the callback should return a promise of an object with the config object:
```tsx title="packages/app/src/App.tsx"
import { createApp } from '@backstage/frontend-app-api';
import { getConfigFromServer } from './utils';
// Example lazy loading the app configuration
const app = createApp({
// Returns Promise<{ config: ConfigApi }>
configLoader: async () => {
// Calls an async utility method that fetches the config object from the server
const config = await getConfigFromServer();
// Feel free to manipulate the config object before returning it
// A common example is conditionally modify the config based on the running enviroment
return { config };
},
});
export default app.createRoot();
```
docs/frontend-system/building-apps/02-built-in-extensions.md
+190
View File
@@ -0,0 +1,190 @@
---
id: built-in-extensions
title: App Built-in Extensions
sidebar_label: Built-in extensions
# prettier-ignore
description: Configuring or overriding built-in extensions
---
Built-in extensions are default app extensions that are always installed when you create a Backstage app.
## Disable built-in extensions
All built-in extensions can be disabled in the same way as you disable any other extension:
```yaml title="app-config.yaml"
extensions:
# Disabling the built-in app root alert element
- app-root-element:app/alert-display: false
```
:::warning
Be careful when disabling built-in extensions, as there may be other extensions depending on their existence. For example, the built-in "alert display" extension displays messages retrieved via [AlertApi](https://backstage.io/docs/reference/core-plugin-api.alertapi) and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`.
:::
## Override built-in extensions
You can override any built-in extension whenever their customizations, whether through configuration or input, do not meet a use case for your Backstage instance. Check out [this](../architecture/05-extension-overrides.md) documentation on how to override application extensions.
:::warning
Be aware there could be some implementation requirements to properly override an built-in extension, such as using same apis and do not remove inputs or configurations otherwise you can cause a side effect in other parts of the system that expects same minimal behavior.
:::
## Default built-in extensions
### App
This extension is the first extension attached to the extension tree. It is responsible for receiving the application's root element and other Frontend framework inputs.
#### Inputs
| Name | Description | Type | Optional | Default | Extension creator |
| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| root | The app root element. | [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata) | false | The [`App/Root`](#app-root) extension output. | No creator available, configure or override the [`App/Root`](#app-root) extension. |
| apis | The app apis factories. | [createApiExtension.factoryDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createapiextension.factorydataref) | false | See [default apis](#default-apis-extensions). | [createApiExtension](https://backstage.io/docs/reference/frontend-plugin-api.createapiextension) |
| themes | The app themes list. | [createThemeExtension.themeDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createthemeextension.themedataref) | false | See [default themes](#default-theme-extensions). | [createThemeExtension](https://backstage.io/docs/reference/frontend-plugin-api.createthemeextension) |
| components | The app components list. | [createComponentExtension.componentDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createcomponentextension.componentdataref) | false | See [default components](#default-components-extensions). | [createComponentExtension](https://backstage.io/docs/reference/frontend-plugin-api.createcomponentextension) |
| translations | The app translations list. | [createTranslationExtension.translationDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createtranslationextension.translationdataref) | false | - | [createTranslationExtension](https://backstage.io/docs/reference/frontend-plugin-api.createtranslationextension) |
#### Default theme extensions
Extensions that provides default theme inputs for the `App` extension.
| kind | namespace | name | id |
| :---: | :-------: | :---: | :---------------: |
| theme | app | light | `theme:app/light` |
| theme | app | dark | `theme:app/dark` |
#### Default components extensions
Extensions that provides default components inputs for the `App` extension.
| kind | namespace | name | id |
| :--------: | :-------: | :-----------------------------------: | :----------------------------------------------------: |
| components | app | core.components.progress | `components:app/core.components.progress` |
| components | app | core.components.notFoundErrorPage | `components:app/core.components.notFoundErrorPage` |
| components | app | core.components.errorBoundaryFallback | `components:app/core.components.errorBoundaryFallback` |
#### Default apis extensions
Extensions that provides default apis inputs for the `App` extension.
| kind | namespace | name | id |
| :--: | :------------------------: | :--: | :------------------------------: |
| api | core.discovery | - | `api:core.discovery` |
| api | core.alert | - | `api:core.alert` |
| api | core.analytics | - | `api:core.analytics` |
| api | core.error | - | `api:core.error` |
| api | core.storage | - | `api:core.storage` |
| api | core.fetch | - | `api:core.fetch` |
| api | core.oauthrequest | - | `api:core.oauthrequest` |
| api | core.auth.google | - | `api:core.auth.google` |
| api | core.auth.microsoft | - | `api:core.auth.microsoft` |
| api | core.auth.github | - | `api:core.auth.github` |
| api | core.auth.okta | - | `api:core.auth.okta` |
| api | core.auth.gitlab | - | `api:core.auth.gitlab` |
| api | core.auth.onelogin | - | `api:core.auth.onelogin` |
| api | core.auth.bitbucket | - | `api:core.auth.bitbucket` |
| api | core.auth.bitbucket-server | - | `api:core.auth.bitbucket-server` |
| api | core.auth.atlassian | - | `api:core.auth.atlassian` |
| api | plugin.permission.api | - | `api:plugin.permission.api` |
### App root
This is the extension that creates the app root element, so it renders root level components such as app router and layout.
#### Inputs
| Name | Description | Requirements | Optional | Default | Extension creator |
| ---------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| router | A React component that should manager the app routes context. | It must be one [router](https://reactrouter.com/en/main/routers/picking-a-router#web-projects) component or a custom component compatible with the 'react-router' library. | true | [BrowserRouter](https://reactrouter.com/en/main/router-components/browser-router) | [createRouterExtension](https://backstage.io/docs/reference/frontend-plugin-api.createrouterextension) |
| signInPage | A React component that should render the app sign-in page. | Should call the `onSignInSuccess` prop when the user has been successfully authorized, otherwise the user will not be correctly redirected to the application home page. | true | The default `AppRoot` extension does not use a default component for this input, it bypasses the user authentication check and always renders all routes when a login page is not installed. | [createSignInPageExtension](https://backstage.io/docs/reference/frontend-plugin-api.createsigninpageextension/) |
| children | A React component that renders the app sidebar and main content in a particular layout. | - | false | The [`App/Layout`](#app-layout) extension output. | No creator available, configure or override the [`App/Layout`](#app-layout) extension. |
| elements | React elements to be rendered outside of the app layout, such as shared popups. | - | false | See [default elements](#default-app-root-elements-extensions). | [createAppRootElementExtension](https://backstage.io/docs/reference/frontend-plugin-api.createapprootelementextension/) |
| wrappers | React components that should wrap the root element. | - | true | - | [createAppRootWrapperExtension](https://backstage.io/docs/reference/frontend-plugin-api.createapprootwrapperextension/) |
#### Default app root elements extensions
##### Alert Display
An app root element extension that displays messages posted via the [`AlertApi`](https://backstage.io/docs/reference/core-plugin-api.alertapi).
| kind | namespace | name | id |
| :--------------: | :-------: | :-----------: | :----------------------------------: |
| app-root-element | app | alert-display | `app-root-element:app/alert-display` |
###### Configurations
| Key | Type | Default value | Description |
| -------------------- | -------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------- |
| `transientTimeoutMs` | number | 5000 | Time in milliseconds to wait before displaying messages. |
| `anchorOrigin` | { vertical: 'top' \| 'bottom', horizontal: 'left' \| 'center' \| 'right' } | { vertical: 'top', horizontal: 'center' } | Position on the screen where the message alert will be displayed. |
###### Override or disable the extension
If you do not want to display alerts, disable this extension or if the available settings do not meet your needs, override this extension.
:::warning
The built-in "alert display" extension displays messages retrieved via [AlertApi](https://backstage.io/docs/reference/core-plugin-api.alertapi) and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`.
:::
##### OAuth Request Dialog
An app root element extension that renders the oauth request dialog, it is based on the [oauthRequestApi](https://backstage.io/docs/reference/core-plugin-api.oauthrequestapi/).
| kind | namespace | name | id |
| :--------------: | :-------: | :------------------: | :-----------------------------------------: |
| app-root-element | app | oauth-request-dialog | `app-root-element:app/oauth-request-dialog` |
### App layout
Renders the app's sidebar and content in a specific layout.
| kind | namespace | name | id |
| :--: | :-------: | :----: | :----------: |
| - | app | layout | `app/layout` |
#### Inputs
| Name | Description | Type | Optional | Default | Extension creator |
| ------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------ |
| nav | A React element that renders the app sidebar. | [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata) | false | - | Override the `App/Nav` extension. |
| content | A React element that renders the app content. | [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata) | false | - | Override the `App/Routes` extension. |
### App nav
Extension responsible for rendering the logo and items in the app's sidebar.
| kind | namespace | name | id |
| :--: | :-------: | :--: | :-------: |
| - | app | nav | `app/nav` |
#### Inputs
| Name | Description | Type | Optional | Default | Extension creator |
| ----- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| logos | A nav logos object. | [createNavLogoExtension.logoElementsDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createnavlogoextension.logoelementsdataref) | true | - | [createNavLogoExtension](https://backstage.io/docs/reference/frontend-plugin-api.createnavlogoextension) |
| items | Nav items target objects. | [createNavItemExtension.targetDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createnavitemextension.targetdataref) | true | - | [createNavItemExtension](https://backstage.io/docs/reference/frontend-plugin-api.createnavitemextension) |
### App routes
Renders a route element for each route received as input and a `NotFoundErrorPage` component.
| kind | namespace | name | id |
| :--: | :-------: | :----: | :----------: |
| - | app | routes | `app/routes` |
#### Caveats
Be careful when overriding this extension, as to do so correctly you must consider these implementation requirements:
- The routing system is managed by more than one extension, and they all use `react-router` behind the scenes. There are also some utilities that are based on the same `routing` library like `useRouteRefParams`. Therefore, you cannot use a different library without causing side effects in these other extensions and helper utilities;
- Don't remove configs or inputs, just extend these things yourself with optional new options, otherwise it will cause breaking changes for extensions like `createPageExtension` that depend on this type of inputs;
- Remember to user the route refs for getting paths dynamically, otherwise if an adopter modifies a path through configuration, the route is not going to point to the configured path;
- Adopters expect to be able to customize the `NotFoundErrorPage` component via Components API, you should render this component for routes not configured.
#### Inputs
| Name | Description | Type | Optional | Default | Extension creator |
| ------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| routes | The route objects list. | `{ path: coreExtensionData.routePath, ref: coreExtensionData.routeRef.optional(), element: coreExtensionData.reactElement }` | false | - | [createPageExtension](https://backstage.io/docs/reference/frontend-plugin-api.createpageextension) |
docs/getting-started/configuration.md
+1 -1
View File
@@ -67,7 +67,7 @@ App. Use the following commands to start the PostgreSQL client installation:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend pg
yarn --cwd packages/backend add pg
```
Use your favorite editor to open `app-config.yaml` and add your PostgreSQL
docs/getting-started/configure-app-with-plugins.md
+1 -1
View File
@@ -23,7 +23,7 @@ to an entity in the software catalog.
```bash
# From your Backstage root directory
yarn add --cwd packages/app @circleci/backstage-plugin
yarn --cwd packages/app add @circleci/backstage-plugin
```
Note the plugin is added to the `app` package, rather than the root
docs/getting-started/homepage.md
+1 -1
View File
@@ -30,7 +30,7 @@ Now, let's get started by installing the home plugin and creating a simple homep
```bash
# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-home
yarn --cwd packages/app add @backstage/plugin-home
```
#### 2. Create a new HomePage component
docs/integrations/aws-s3/discovery.md
+1 -1
View File
@@ -64,7 +64,7 @@ the AWS catalog plugin:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-aws
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-aws
```
Once you've done that, you'll also need to add the segment below to `packages/backend/src/plugins/catalog.ts`:
docs/integrations/azure/discovery.md
+1 -1
View File
@@ -98,7 +98,7 @@ the Azure catalog plugin:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-azure
yarn --cwd packages/backend add @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`:
docs/integrations/azure/org.md
+1 -1
View File
@@ -16,7 +16,7 @@ The package is not installed by default, therefore you have to add `@backstage/p
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-msgraph
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-msgraph
```
Next add the basic configuration to `app-config.yaml`
docs/integrations/bitbucketCloud/discovery.md
+1 -1
View File
@@ -21,7 +21,7 @@ package.
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-bitbucket-cloud
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-bitbucket-cloud
```
### Installation without Events Support
docs/integrations/bitbucketServer/discovery.md
+1 -1
View File
@@ -21,7 +21,7 @@ package.
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-bitbucket-server
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-bitbucket-server
```
And then add the entity provider to your catalog builder:
docs/integrations/gerrit/discovery.md
+1 -1
View File
@@ -18,7 +18,7 @@ the Gerrit provider plugin:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-gerrit
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-gerrit
```
Then add the plugin to the plugin catalog `packages/backend/src/plugins/catalog.ts`:
docs/integrations/github/discovery.md
+2 -2
View File
@@ -23,7 +23,7 @@ package.
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-github
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github
```
And then add the entity provider to your catalog builder:
@@ -250,7 +250,7 @@ package, plus `@backstage/integration` for the basic credentials management:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/integration @backstage/plugin-catalog-backend-module-github
yarn --cwd packages/backend add @backstage/integration @backstage/plugin-catalog-backend-module-github
```
And then add the processors to your catalog builder:
docs/integrations/github/org.md
+2 -2
View File
@@ -27,7 +27,7 @@ to `@backstage/plugin-catalog-backend-module-github` to your backend package.
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-github
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github
```
> Note: When configuring to use a Provider instead of a Processor you do not
@@ -308,7 +308,7 @@ install and register it in the catalog plugin:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-github
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github
```
```typescript title="packages/backend/src/plugins/catalog.ts"
docs/integrations/gitlab/discovery.md
+1 -1
View File
@@ -39,7 +39,7 @@ the gitlab catalog plugin:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-gitlab
yarn --cwd packages/backend add @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`:
docs/integrations/gitlab/org.md
+1 -1
View File
@@ -15,7 +15,7 @@ As this provider is not one of the default providers, you will first need to ins
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-gitlab
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-gitlab
```
Then add the plugin to the plugin catalog `packages/backend/src/plugins/catalog.ts`:
docs/integrations/ldap/org.md
+1 -1
View File
@@ -26,7 +26,7 @@ to `@backstage/plugin-catalog-backend-module-ldap` to your backend package.
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-ldap
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-ldap
```
> Note: When configuring to use a Provider instead of a Processor you do not
docs/local-dev/cli-build-system.md
+7 -6
View File
@@ -258,7 +258,7 @@ When building CommonJS or ESM output, the build commands will always use
`src/index.ts` as the entrypoint. All non-relative modules imports are considered
external, meaning the Rollup build will only compile the source code of the package
itself. All import statements of external dependencies, even within the same
monorepo, will stay intact.
[monorepo](../references/glossary.md#monorepo), will stay intact.
The build of the type definitions works quite differently. The entrypoint of the
type definition build is the relative location of the package within the
@@ -307,11 +307,12 @@ support for them instead.
### Frontend Production
The frontend production bundling creates your typical web content bundle, all
contained within a single folder, ready for static serving. It is used when building
packages with the `'frontend'` role, and unlike the development bundling there is no way to
build a production bundle of an individual plugin. The output of the bundling
process is written to the `dist` folder in the package.
The frontend production bundling creates your typical web content
[bundle](../references/glossary.md#bundle), all contained within a single
folder, ready for static serving. It is used when building packages with the
`'frontend'` role, and unlike the development bundling there is no way to
build a production bundle of an individual plugin.
The output of the bundling process is written to the `dist` folder in the package.
Just like the development bundling, the production bundling is based on
[Webpack](https://webpack.js.org/). It uses the
docs/local-dev/cli-overview.md
+3 -17
View File
@@ -7,11 +7,12 @@ description: Overview of the Backstage CLI
## Introduction
A goal of Backstage is to provide a delightful developer experience in and
around the project. Creating new apps and plugins should be simple, iteration
around the project. Creating new [apps](../references/glossary.md#app) and
[plugins](../references/glossary.md#plugin) should be simple, iteration
speed should be fast, and the overhead of maintaining custom tooling should be
minimal. As a part of accomplishing this goal, Backstage provides its own build
system and tooling, delivered primarily through the
[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package. When
[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) [package](../references/glossary.md#package). When
creating an app using
[`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app),
you receive a project that's already prepared with a typical setup and package
@@ -36,18 +37,3 @@ The Backstage CLI intentionally does not provide many hooks for overriding or
customizing the build process. This is to allow for evolution of the CLI without
having to take a wide API surface into account. This allows us to iterate and
improve the tooling, as well as to more easily keep the system up to date.
## Glossary
- **Package** - A package in the Node.js ecosystem, often published to a package
registry such as [NPM](https://www.npmjs.com/).
- **Monorepo** - A project layout that consists of multiple packages within a
single project, where packages are able to have local dependencies on each
other. Often enabled through tooling such as [lerna](https://lerna.js.org/)
and [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)
- **Local Package** - One of the packages within a monorepo. These package may
or may not also be published to a package registry.
- **Bundle** - A collection of the deployment artifacts. The output of the
bundling process, which brings a collection of packages into a single
collection of deployment artifacts.
- **Package Role** - The declared role of a package, see [package roles](./cli-build-system.md#package-roles).
docs/openapi/01-getting-started.md
+3 -3
View File
@@ -45,7 +45,7 @@ You should create a new folder, `src/schema` in your backend plugin to store you
## Generating a typed express router from a spec
Run `yarn backstage-repo-tools schema openapi generate <plugin-directory>`. This will create an `openapi.generated.ts` file in the `src/schema` directory that contains the OpenAPI schema as well as a generated express router with types.
Run `yarn backstage-repo-tools package schema openapi generate --server` from the directory with your plugin. This will create an `openapi.generated.ts` file in the `src/schema` directory that contains the OpenAPI schema as well as a generated express router with types. You should add this command to your `package.json` for future use and you can combine both the server generation and the client generation below like so, `yarn backstage-repo-tools package schema openapi generate --server --client-package <clientPackageDirectory>`
Use it like so, update your `router.ts` or `createRouter.ts` file with the following content,
@@ -63,7 +63,7 @@ export async function createRouter(
## Generating a typed client from a spec
Run `yarn backstage-repo-tools schema openapi generate-client --input-spec <plugin-directory>/src/schema/openapi.yaml --output-directory <plugin-client-directory>`. `<plugin-directory>` should match the same backend plugin we've been using so far. `<plugin-client-directory>` is a new directory and npm package that you should create. The general pattern is `plugins/<plugin-name>-client`.
From your current backend plugin directory, run `yarn backstage-repo-tools package schema openapi generate --client-package <plugin-client-directory>`. `<plugin-client-directory>` is a new directory and npm package that you should create. The general pattern is `plugins/<plugin-name>-client` or if you want to co-locate this with your other shared types, use `plugins/<plugin-name>-common`. You should add this command to your `package.json` for future use.
The generated client will have a directory `src/generated` that exports a `DefaultApiClient` class and all generated types. You can use the client like so,
@@ -108,7 +108,7 @@ describe('createRouter', () => {
+ app = wrapInOpenApiTestServer(express().use(router));
```
This adds a wrapper around the express server that allows it to reroute traffic for `supertest`. Run `yarn backstage-repo-tools schema openapi init` to create some required config files. Now, when you run `yarn backstage-repo-tools schema openapi test` your schema will now be tested against your test data. Any errors will be reported.
This adds a wrapper around the express server that allows it to reroute traffic for `supertest`. Run `yarn backstage-repo-tools package schema openapi init` to create some required files. Now, when you run `yarn backstage-repo-tools repo schema openapi test` your schema will now be tested against your test data. Any errors will be reported.
Our command is a small wrapper over [`Optic`](https://github.com/opticdev/optic) which does all of the heavy lifting.
docs/openapi/generate-client.md
+2 -2
View File
@@ -4,7 +4,7 @@ title: Generate a client from your OpenAPI spec
description: Documentation on how to create a client for a given OpenAPI spec
---
## How to generate a client with `repo-tools schema openapi generate-client`?
## How to generate a client with `repo-tools package schema openapi generate client`?
### Prerequisites
@@ -20,7 +20,7 @@ info:
### Generating your client
1. Run `yarn backstage-repo-tools schema openapi generate-client --input-spec <file> --output-directory <directory>`. This will create a new folder in `<directory>/src/generated` to house the generated content.
1. Run `yarn backstage-repo-tools schema openapi generate client --output-package <directory>`. This will create a new folder in `<directory>/src/generated` to house the generated content.
2. You should use the generated files as follows,
- `apis/DefaultApi.client.ts` - this is the client that you should use. It has types for all of the various operations on your API.
docs/openapi/test-case-validation.md
+3 -3
View File
@@ -1,15 +1,15 @@
---
id: test-case-validation
title: Validate your OpenAPI spec against test data
description: Documentation on how to use the `schema openapi test` command.
description: Documentation on how to use the `repo schema openapi test` command.
---
## OpenAPI Validation using Test Cases
This is primarily performed by `backstage-repo-tools schema openapi test`. Any errors found in the generated specs can be either
This is primarily performed by `backstage-repo-tools repo schema openapi test`. Any errors found in the generated specs can be either
1. Fixed manually, this is usually relevant for request body or response body changes.
2. Fixed automatically with `backstage-repo-tools schema openapi test --update`.
2. Fixed automatically with `backstage-repo-tools repo schema openapi test --update`.
3. Fixing the test case. This can happen where a response is mocked as
```ts
docs/overview/background.md
+1 -1
View File
@@ -35,4 +35,4 @@ Backstage was originally built by Spotify and then donated to the CNCF.
Backstage is currently in the Incubation phase. Read the announcement
[here](https://backstage.io/blog/2022/03/16/backstage-turns-two#out-of-the-sandbox-and-into-incubation).
<img src="https://backstage.io/img/cncf-white.svg" width="400" />
<img src="https://backstage.io/img/cncf-white.svg" alt="CNCF logo" width="400" />
docs/overview/glossary.md
-26
View File
@@ -1,26 +0,0 @@
---
id: glossary
title: Backstage Glossary
# prettier-ignore
description: List of terms, abbreviations, and phrases used in Backstage, together with their explanations.
---
The Backstage Glossary lists terms, abbreviations, and phrases used in
Backstage, together with their explanations. We encourage you to use the
terminology below for clarity and consistency when discussing Backstage.
See also [Authentication Glossary](../auth/glossary.md), a separate glossary of terms and phrases
specifically related to the authentication and identity section of Backstage.
### Backstage User Profiles
There are three main user profiles for Backstage: the integrator, the
contributor, and the end user (typically a software engineer).
| Term | Explanation |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integrator | The **integrator** hosts the Backstage app and configures which plugins are available to use in the app. |
| Contributor | The **contributor** adds functionality to the app by writing plugins. |
| End user | The **end user** uses the app's functionality and interacts with its plugins. This profile covers the various roles that help deliver software. The typical end user is a **software engineer**, but users might also consider themselves _designers_, _data scientists_, _product owners_, _engineering managers_, _technical writers_, and so on. |
| Software engineer | The **software engineer** is an **end user** who uses the app's functionality and interacts with its plugins in the course of writing and documenting code. This user is more likely to embed documentation in the code files they produce, and create rough drafts of conceptual pages in collaboration with a **technical writer** or _technical editor_. |
| Technical writer | The **technical writer** is an **end user** who uses the app's functionality and interacts with its plugins in the course of writing and editing documentation. This user is more likely to produce and customize templates and produce conceptual pages to supplement documentation embedded in code files. |
docs/overview/logos.md
+14 -14
View File
@@ -12,31 +12,31 @@ The assets below are all in `.svg` format. Other formats are available in the
## Backstage logo
<a href="https://backstage.io/logo_assets/svg/Logo_White.svg">
<img src="https://backstage.io/logo_assets/svg/Logo_White.svg" width="600" />
<a href="https://backstage.io/logo_assets/svg/Logo_White.svg" aria-label='Link to Backstage White logo svg'>
<img src="https://backstage.io/logo_assets/svg/Logo_White.svg" alt='Backstage White logo' width="600" />
</a>
<a href="https://backstage.io/logo_assets/svg/Logo_Teal.svg">
<img src="https://backstage.io/logo_assets/svg/Logo_Teal.svg" width="600" />
<a href="https://backstage.io/logo_assets/svg/Logo_Teal.svg" aria-label='Link to Backstage Teal logo svg'>
<img src="https://backstage.io/logo_assets/svg/Logo_Teal.svg" alt='Backstage Teal logo' width="600" />
</a>
<a href="https://backstage.io/logo_assets/svg/Logo_Black.svg">
<img src="https://backstage.io/logo_assets/svg/Logo_Black.svg" width="600" className="logoWhite" class="logoWhite" />
<a href="https://backstage.io/logo_assets/svg/Logo_Black.svg" aria-label='Link to Backstage Black logo svg'>
<img src="https://backstage.io/logo_assets/svg/Logo_Black.svg" alt='Backstage Black logo' width="600" className="logoWhite" class="logoWhite" />
</a>
## Backstage icon
<div>
<a href="https://backstage.io/logo_assets/svg/Icon_White.svg">
<img src="https://backstage.io/logo_assets/svg/Icon_White.svg" width="180" height="180" />
<a href="https://backstage.io/logo_assets/svg/Icon_White.svg" aria-label='Link to Backstage White icon'>
<img src="https://backstage.io/logo_assets/svg/Icon_White.svg" alt='Backstage White Icon' width="180" height="180" />
</a>
<a href="https://backstage.io/logo_assets/svg/Icon_Teal.svg">
<img src="https://backstage.io/logo_assets/svg/Icon_Teal.svg" width="180" height="180" />
<a href="https://backstage.io/logo_assets/svg/Icon_Teal.svg" aria-label='Link to Backstage Teal icon'>
<img src="https://backstage.io/logo_assets/svg/Icon_Teal.svg" alt='Backstage Teal Icon' width="180" height="180" />
</a>
<a href="https://backstage.io/logo_assets/svg/Icon_Gradient.svg">
<img src="https://backstage.io/logo_assets/svg/Icon_Gradient.svg" width="180" height="180" />
<a href="https://backstage.io/logo_assets/svg/Icon_Gradient.svg" aria-label='Link to Backstage Gradient icon'>
<img src="https://backstage.io/logo_assets/svg/Icon_Gradient.svg" alt='Backstage Gradient Icon' width="180" height="180" />
</a>
<a href="https://backstage.io/logo_assets/svg/Icon_Black.svg">
<img src="https://backstage.io/logo_assets/svg/Icon_Black.svg" width="180" height="180" className="logoWhite" class="logoWhite" />
<a href="https://backstage.io/logo_assets/svg/Icon_Black.svg" aria-label='Link to Backstage Black icon'>
<img src="https://backstage.io/logo_assets/svg/Icon_Black.svg" alt='Backstage Black Icon' width="180" height="180" className="logoWhite" class="logoWhite" />
</a>
</div>
docs/overview/support.md
+1 -39
View File
@@ -6,11 +6,11 @@ description: Support and Community Details and Links
- [Discord chatroom](https://discord.gg/backstage-687207715902193673) - Get support or discuss the
project.
- [Stack Overflow](https://stackoverflow.com/questions/tagged/backstage) - Browse or ask questions on Stack Overflow.
- [Good First Issues](https://github.com/backstage/backstage/contribute) - Start
here if you want to contribute.
- [RFCs](https://github.com/backstage/backstage/labels/rfc) - Help shape the
technical direction by reviewing _Request for Comments_ issues.
- [BEPs](https://github.com/backstage/backstage/tree/master/beps#backstage-enhancement-proposals-beps) - A Backstage Enhancement Proposal (BEP) is a way to propose, communicate and coordinate on new efforts for the Backstage project.
- [FAQ](../faq/index.md) - Frequently Asked Questions.
- [Code of Conduct](https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md) -
This is how we roll.
@@ -23,41 +23,3 @@ description: Support and Community Details and Links
## Community Hub
Check out the Backstage.io [Backstage Community Hub](https://backstage.io/community) for the Community Sessions, recordings, and community resources.
### Adding a recording to the meetup page
To add a new recording to the [meetup page](https://backstage.io/on-demand)
create a file in
[`microsite/data/on-demand`](https://github.com/backstage/backstage/tree/master/microsite/data/on-demand)
with your recording's information. Filenames should be in the format `yyyymmdd-xx.yaml`. The page will sort using the filename. Example file content:
```yaml
---
title: # name of the meetup
date: February 23, 2022 # date, format: Month day, year.
category: Meetup # Can be Event, Meetup, Webinar
description: # description, summary
youtubeUrl: # Url to youtube video
youtubeImgUrl: # Url to the preview image, for Youtube this is the format: https://i1.ytimg.com/vi/<YOUTUBE_ID>/mqdefault.jpg
```
### Adding an upcoming meetup to the meetup page
To add an upcoming meetup to the [meetup page](https://backstage.io/on-demand)
create a file in
[`microsite/data/on-demand`](https://github.com/backstage/backstage/tree/master/microsite/data/on-demand)
with your meetup's information. Filenames should be in the format `yyyymmdd-xx.yaml`, the page will sort using the filename. Example file content:
```yaml
---
title: # name of the meetup
date: February 23, 2022 # date, format: Month day, year.
category: Upcoming # Should be "Upcoming"
description: # description, summary
youtubeUrl: # Url to youtube video
youtubeImgUrl: # Url to the preview image, for Youtube this is the format: https://i1.ytimg.com/vi/<YOUTUBE_ID>/mqdefault.jpg
rsvpUrl: # Link to registration, calendar item, etc
eventUrl: # Link to event landing page
```
After the meetup is done, and the recording is ready you can change it to a meetup recording.
docs/overview/what-is-backstage.md
+1 -1
View File
@@ -40,7 +40,7 @@ Out of the box, Backstage includes:
Backstage is a CNCF Incubation project after graduating from Sandbox. Read the announcement
[here](https://backstage.io/blog/2022/03/16/backstage-turns-two#out-of-the-sandbox-and-into-incubation).
<img src="https://backstage.io/img/cncf-white.svg" width="400" />
<img src="https://backstage.io/img/cncf-white.svg" alt="CNCF logo" width="400" />
## Benefits
docs/permissions/concepts.md
+6 -4
View File
@@ -6,11 +6,11 @@ description: A list of important permission framework concepts
### Permission
Any action that a user performs within Backstage may be represented as a permission. More complex actions, like executing a software template, may require authorization for multiple permissions throughout the flow. Permissions are identified by a unique name and optionally include a set of attributes that describe the corresponding action. Plugins are responsible for defining and exposing the permissions they enforce.
Any action that a user performs within Backstage may be represented as a permission. More complex actions, like executing a [software template](../references/glossary.md#software-templates), may require [authorization](../references/glossary.md#authorization) for multiple permissions throughout the flow. Permissions are identified by a unique name and optionally include a set of attributes that describe the corresponding action. [Plugins](../references/glossary.md#plugin) are responsible for defining and exposing the permissions they enforce as well as enforcing restrictions from the permission framework.
### Policy
User permissions are authorized by a central, user-defined permission policy. At a high level, a policy is a function that receives a Backstage user and permission, and returns a decision to allow or deny. Policies are expressed as code, which decouples the framework from any particular authorization model, like role-based access control (RBAC) or attribute-based access control (ABAC).
User [permissions](../references/glossary.md#permission-permission-plugin) are authorized by a central, user-defined permission policy. At a high level, a policy is a function that receives a Backstage user and permission, and returns a decision to allow or deny. Policies are expressed as code, which decouples the framework from any particular [authorization](../references/glossary.md#authorization) model, like role-based access control (RBAC) or attribute-based access control (ABAC).
### Policy decision versus enforcement
@@ -18,8 +18,10 @@ Two important responsibilities of any authorization system are to decide if a us
### Resources and rules
In many cases, a permission represents a user's interaction with another object. This object likely has information that policy authors can use to define more granular access. The permission framework introduces two abstractions to account for this: resources and rules. Resources represent the objects that users interact with. Rules are predicate-based controls that tap into a resource's data. For example, the catalog plugin defines a resource for catalog entities and a rule to check if an entity has a given annotation.
In many cases, a permission represents a user's interaction with another object. This object likely has information that policy authors can use to define more granular access. The permission framework introduces two abstractions to account for this: [resources](../references/glossary.md#resource-permission-plugin) and [rules](../references/glossary.md#rule-permission-plugin). For example, the catalog plugin defines a resource for catalog entities and a rule to check if an entity has a given annotation.
### Conditional decisions
Rules need additional data before they can be used in a decision. For example, the catalog plugin's "has annotation" rule needs to know what annotation to look for on a given entity. Once a rule is bound to relevant information it forms a condition. Conditions are then used to return a conditional decision from a policy. Conditional decisions tell the permission framework to delegate evaluation to the plugin that owns the corresponding resource. Permission requests that result in a conditional decision are allowed if all of the provided conditions evaluate to be true. This conditional behavior avoids coupling between policies and resource schemas, and allows plugins to evaluate complex rules in an efficient way. For example, a plugin may convert a conditional decision to a database query instead of loading and filtering objects in memory.
[Rules](../references/glossary.md#rule-permission-plugin) need additional data before they can be used in a decision. Once a [rule](../references/glossary.md#rule-permission-plugin) is bound to relevant information it forms a [condition](../references/glossary.md#condition-permission-plugin). Conditional decisions tell the [permission framework](#permission) to delegate evaluation to the [plugin](#plugin) that owns the corresponding [resource](#resource-permission-plugin). Permission requests that result in a conditional decision are allowed if all of the provided conditions evaluate to be true.
A good example would be the catalog plugin's "has annotation" rule which needs to know what annotation to look for on a given entity. The permission framework would respond to a request by the catalog plugin in this case with a condition decision. The catalog plugin would then need to correctly filter for entities matching the "has annotations" condition. This conditional behavior avoids coupling between policies and resource schemas, and allows plugins to evaluate complex rules in an efficient way. For example, a plugin may convert a conditional decision to a database query instead of loading and filtering objects in memory.
docs/permissions/custom-rules.md
+1 -1
View File
@@ -4,7 +4,7 @@ title: Defining custom permission rules
description: How to define custom permission rules for existing resources
---
For some use cases, you may want to define custom [rules](./concepts.md#resources-and-rules) in addition to the ones provided by a plugin. In the [previous section](./writing-a-policy.md) we used the `isEntityOwner` rule to control access for catalog entities. Let's extend this policy with a custom rule that checks what [system](https://backstage.io/docs/features/software-catalog/system-model#system) an entity is part of.
For some use cases, you may want to define custom [rules](../references/glossary.md#rule-permission-plugin) in addition to the ones provided by a plugin. In the [previous section](./writing-a-policy.md) we used the `isEntityOwner` rule to control access for catalog entities. Let's extend this policy with a custom rule that checks what [system](https://backstage.io/docs/features/software-catalog/system-model#system) an entity is part of.
## Define a custom rule
docs/permissions/getting-started.md
+1 -1
View File
@@ -48,7 +48,7 @@ The permissions framework uses a new `permission-backend` plugin to accept autho
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-permission-backend
yarn --cwd packages/backend add @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.
docs/permissions/overview.md
+1 -1
View File
@@ -22,7 +22,7 @@ The permission framework was designed with a few key properties in mind:
- **Integrators** can author or configure policies that define which users can take certain actions upon which resources.
![](../assets/permissions/permission-framework-overview.drawio.svg)
![backstage framework overview](../assets/permissions/permission-framework-overview.drawio.svg)
1. The user triggers a request to perform some action. The request specifies the authorization details using the permission specified by the plugin (in this case, a resource read action).
docs/permissions/plugin-authors/01-setup.md
+2 -2
View File
@@ -41,8 +41,8 @@ The source code is available here:
```sh
# From your Backstage root directory
yarn add --cwd packages/backend @internal/plugin-todo-list-backend @internal/plugin-todo-list-common
yarn add --cwd packages/app @internal/plugin-todo-list
yarn --cwd packages/backend add @internal/plugin-todo-list-backend @internal/plugin-todo-list-common
yarn --cwd packages/app add @internal/plugin-todo-list
```
3. Include the backend and frontend plugin in your application:
docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md
+2 -2
View File
@@ -4,9 +4,9 @@ title: 2. Adding a basic permission check
description: Explains how to add a basic permission check to a Backstage plugin
---
If the outcome of a permission check doesn't need to change for different [resources](../concepts.md#resources-and-rules), you can use a _basic permission check_. For this kind of check, we simply need to define a [permission](../concepts.md#resources-and-rules), and call `authorize` with it.
If the outcome of a permission check doesn't need to change for different [resources](../../references/glossary.md#resource-permission-plugin), you can use a _basic permission check_. For this kind of check, we simply need to define a permission, and call `authorize` with it.
For this tutorial, we'll use a basic permission check to authorize the `create` endpoint in our todo-backend. This will allow Backstage integrators to control whether each of their users is authorized to create todos by adjusting their [permission policy](../concepts.md#policy).
For this tutorial, we'll use a basic permission check to authorize the `create` endpoint in our todo-backend. This will allow Backstage integrators to control whether each of their users is authorized to create todos by adjusting their [permission policy](../../references/glossary.md#policy-permission-plugin).
We'll start by creating a new permission, and then we'll use the permission api to call `authorize` with it during todo creation.
docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md
+1 -1
View File
@@ -4,7 +4,7 @@ title: 3. Adding a resource permission check
description: Explains how to add a resource permission check to a Backstage plugin
---
When performing updates (or other operations) on specific [resources](../concepts.md#resources-and-rules), the permissions framework allows for the decision to be based on characteristics of the resource itself. This means that it's possible to write policies that (for example) allow the operation for users that own a resource, and deny the operation otherwise.
When performing updates (or other operations) on specific [resources](../../references/glossary.md#resource-permission-plugin), the permissions framework allows for the decision to be based on characteristics of the resource itself. This means that it's possible to write policies that (for example) allow the operation for users that own a resource, and deny the operation otherwise.
## Creating the update permission
docs/plugins/backend-plugin.md
+1 -1
View File
@@ -69,7 +69,7 @@ to your backend.
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @internal/plugin-carmen-backend@^0.1.0 # Change this to match the plugin's package.json
yarn --cwd packages/backend add @internal/plugin-carmen-backend@^0.1.0 # Change this to match the plugin's package.json
```
Create a new file named `packages/backend/src/plugins/carmen.ts`, and add the
docs/publishing.md
+23 -1
View File
@@ -140,4 +140,26 @@ process is used to release an emergency fix as version `6.5.1` in the patch rele
### When the release workflow is not triggered for some reason, such as a GitHub incident
Ask one of the maintainers to force push master back to a previous commit and then push the release merge commit again.
Ask one of the maintainers to trigger [the Deploy packages](https://github.com/backstage/backstage/actions/workflows/deploy_packages.yml) workflow with the "Unconditionally trigger the release job to run" checkbox set, on the `master` branch. Please validate first that nothing substantial has been pushed to master since the original failed release attempt! For this reason, it is wise to have the master branch locked until each release has gone through.
### The release successfully published packages but failed when finalizing the release
If it's an intermittent failure then it is safe to re-trigger the release workflow again.
If re-triggering doesn't or won't help, the following steps can be taken to complete the release:
- Manually create a git tag for the release if it doesn't already exist
- Manually create a [new GitHub release](https://github.com/backstage/backstage/releases/new).
- Trigger the repository dispatch workflow using the following request, replace `<VERSION>` with the release version **without** the `v` prefix:
```shell
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer $(gh auth token)" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/repos/backstage/backstage/dispatches \
-d '{"event_type":"release-published","client_payload":{"version":"<VERSION>"}}'
```
- Manually post a message on Discord in the #announcements channel
docs/references/glossary.md
+314
View File
@@ -0,0 +1,314 @@
---
id: glossary
title: Glossary
# prettier-ignore
description: List of terms, abbreviations, and phrases used in Backstage, together with their explanations.
---
## Access Token
A [token](#token) that gives access to perform actions on behalf of a user. It will commonly have a short expiry time, and be limited to a set of [scopes](#scope). Part of the [OAuth](#oauth) protocol, see [their docs](https://oauth.net/2/access-tokens/) for more information.
## Administrator
Someone responsible for installing and maintaining a Backstage [app](#app) for an organization. A [user role](#user-role).
## API (catalog plugin)
An [entity](#entity) representing a schema that two [components](#component) use to communicate. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
## App
An installed instance of Backstage. An app can be local, intended for a single development group or individual developer, or organizational, for use by an entire enterprise.
## Authorization Code
A type of [OAuth flow](#oauth) used by confidential and public clients to get an [access token](#access-token). See [the OAuth docs](https://oauth.net/2/grant-types/authorization-code/) for more details.
## Backstage
1. A platform for creating and deploying [developer portals](#developer-portal), originally created at Spotify. Backstage is an incubation-stage open source project of the [Cloud Native Computing Foundation](#cloud-native-computing-foundation).
2. [The Backstage Framework](#backstage-framework).
## Backstage Framework
The actual framework that Backstage [plugins](#plugin) sit on. This spans both the frontend and the backend, and includes core functionality such as declarative integration, config reading, database management, and many more.
## Bundle
1. A collection of [deployment artifacts](#deployment-artifacts).
2. The output of the bundling process, which brings a collection of [packages](#package) into a single collection of [deployment artifacts](#deployment-artifacts).
## Catalog
1. The core Backstage plugin that handle ingestion and display of your organizations software products.
2. An organization's portfolio of software products managed in Backstage.
## Cloud Native Computing
A set of technologies that "empower organizations to build and run scalable applications in modern, dynamic environments such as public, private, and hybrid clouds. Containers, service meshes, microservices, immutable infrastructure, and declarative APIs exemplify this approach." ([CNCF Cloud Native Definition v1.0](https://github.com/cncf/toc/blob/main/DEFINITION.md)).
## Cloud Native Computing Foundation
A foundation dedicated to the promotion and advancement of [Cloud Native Computing](#Cloud-Native-Computing). The mission of the Cloud Native Computing Foundation (CNCF) is "to make cloud native computing ubiquitous" ([CNCF Charter](https://github.com/cncf/foundation/blob/main/charter.md)).
CNCF is part of the [Linux Foundation](https://www.linuxfoundation.org/).
## CNCF
Cloud Native Computing Foundation.
## Code Grant
[OAuth](#oauth) flow where the client receives an [authorization code](#code) that is passed to the backend to be exchanged for an [access token](#access-token) and possibly a [refresh token](#refresh-token).
## Collator (search plugin)
A transformer that takes streams of [documents](#documents) and outputs searchable texts. They're usually responsible for the data transformation and definition and collection process for specific [documents](#documents).
## Component (catalog plugin)
A software product that is managed in the Backstage [Software Catalog](#software-catalog). A component can be a service, website, library, data pipeline, or any other piece of software managed as a single project. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
## Condition (permission plugin)
A mapping from a given entity to criteria a user must fulfill to perform an action on that entity. Examples include `isOwner`, `hasRole`, etc.
## Conditional Decision (permission plugin)
A type of [decision](#policy-decision-permission-plugin) that allows for per-user evaluation of [conditions](#condition-permission-plugin) against a [resource](#resource-permission-plugin). See [Conditional Decisions](../permissions/concepts.md#conditional-decisions)
## Contributor
A volunteer who helps to improve an OSS product such as Backstage. This volunteer effort includes coding, testing, technical writing, user support, and other work. A [user role](#user-role).
## Declarative Integration
A new paradigm for Backstage frontend plugins, allowing definition in config files instead of hosting complete React pages. See [the Frontend System](https://backstage.io/docs/frontend-system).
## Decorator (search plugin)
A transform stream that allows you to add additional information to [documents](#document-search-plugin).
## Deployment Artifacts
An executable or package file with all of the necessary information required to deploy the application at runtime. Deployment artifacts can be hosted on [package registries](#package-registry).
## Developer
1. Someone who writes code and develops software.
2. A [user role](#user-role) defined as someone who uses a Backstage [app](#app). Might or might not actually be a software developer.
## Developer Portal
A centralized system comprising a user interface and database used to facilitate and document all the software projects within an organization. Backstage is both a developer portal and (by virtue of being based on plugins) a platform for creating developer portals.
## Document (search plugin)
An abstract concept representing something that can be found by searching for it. A document can represent a software entity, a TechDocs page, etc. Documents are made up of metadata fields, at a minimum -- a title, text, and location (as in a URL).
## Domain
An area that relates systems or entities to a business unit. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
## Entity
What is cataloged in the Backstage Software Catalog. An entity is identified by a unique combination of [kind](#Kind), [namespace](#Namespace), and name. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
## Evaluator
Someone who assesses whether Backstage is a suitable solution for their organization. The only [user role](#user-role) with a pre-deployment [use case](#use-case).
## ID Token
A [JWT](#jwt) used to prove a user's identity, containing for example the user's email. Part of [OpenID Connect](#openid-connect).
## Index (search plugin)
An index is a collection of [documents](#documents) of a given type.
## Indexer (search plugin)
A write stream of [documents](#documents).
## Integrator
Someone who develops one or more plugins that enable Backstage to interoperate with another software system. A [user role](#user-role).
## JWT
JSON Web Token.
A popular JSON based token format that is commonly encrypted and/or signed, see [the Wikipedia article](https://en.wikipedia.org/wiki/JSON_Web_Token) for more details.
## Kind
Classification of an [entity](#Entity) in the Backstage Software Catalog, for example _service_, _database_, and _team_.
## Kubernetes (CNCF Project)
An open-source system for automating deployment, scaling, and management of containerized applications.
## Kubernetes (Backstage plugin)
A core Backstage plugin enabling a service owner-focused view of Kubernetes resources.
## Local Package
One of the [packages](#package) within a [monorepo](#monorepo). These package may or may not also be published to a [package registry](#package-registry).
## Monorepo
1. A single repository for a collection of related software projects, such as all projects belonging to an organization.
2. A project layout that consists of multiple [packages](#package) within a single project, where packages are able to have local dependencies on each other. Often enabled through tooling such as [lerna](https://lerna.js.org/) and [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)
## Namespace (catalog plugin)
An optional attribute that can be used to organize [entities](#entity).
## Objective
A high level goal of a [user role](#User-Role) interacting with Backstage. Some goals of the _administrator_ user role, for example, are to maintain an instance ("app") of Backstage; to add and update functionality via plugins; and to troubleshoot issues.
## OAuth
Refers to: OAuth 2.0, a standard protocol for authorization. See [oauth.net/2/](https://oauth.net/2/).
## Offline Access
[OAuth](#oauth) flow that results in both a refresh token and [access token](#access-token), where the refresh token has a long expiration or never expires, and can be used to request more access tokens in the future. This lets the user go "offline" with respect to the token issuer, but still be able to request more tokens at a later time without further direct interaction for the user.
## OpenID Connect
A layer on top of [OAuth](#oauth) which standardises authentication. See [the Wikipedia article](https://en.wikipedia.org/wiki/OpenID_Connect) for more details.
## OSS
Open source software.
## Package
A package in the Node.js ecosystem, often published to a [package registry](#package-registry).
## Package Registry
A service that hosts [packages](#package). The most prominent example is [NPM](https://www.npmjs.com/).
## Package Role
The declared role of a package, see [package roles](../local-dev/cli-build-system.md#package-roles).
## Permission (core Backstage plugin)
A core Backstage plugin and framework that allows restriction of actions to specific users. See [their docs](https://backstage.io/docs/permissions/overview) for more information.
## Permission (permission plugin)
A restriction on any action that a user can perform against a specific [resource](#resource-permission-plugin) or set of resources. See [the permission framework docs](../permissions/concepts.md#permission) for more details.
## Persona (use cases)
Alternative term for a [User Role](#user-role).
## Plugin
A module in Backstage that adds a feature. All functionality outside of [the Backstage framework](#backstage-framework), even the core features, are implemented as plugins.
## Policy (permission plugin)
A construct that takes in a Backstage user and a [permission](#permission-permission-plugin) and returns a [policy decision](#policy-decision-permission-plugin).
## Policy Decision (permission plugin)
A specific response to a user's request to perform an action on a list of [resources](#resource-permission-plugin). Can be either `Approve`, `Deny` or [`Conditional`](#conditional-decision-permission-plugin).
## Popup
A separate browser window opened on top of the previous one.
## Procedure (use cases)
A set of actions that accomplish a goal, usually as part of a [use case](#Use-Case). A procedure can be high-level, containing other procedures, or can be as simple as a single [task](#Task).
## Query Translators (search plugin)
An abstraction layer between a search engine and the [Backstage Search](#search) backend. Allows for translation into queries against your search engine.
## Refresh token
A special token that an [OAuth](#oauth) client can use to get a new [access token](#access-token) when the latter expires.
https://oauth.net/2/refresh-tokens/
## Resource (catalog plugin)
An [entity](#entity) that represents a piece of physical or virtual infrastructure, for example a database, required by a component. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
## Resource (permission plugin)
A representation of an object that a user interacts with and that can be permissioned. Not to be confused with [Software Catalog resources](#resource-catalog-plugin).
## Rule (permission plugin)
A predicate-based control that taps into a [resource](#resource-permission-plugin)'s data.
## Role
See [User Role](#User-Role).
## Scaffolder
Known as [Software Templates](#software-templates).
## Scope
A string that describes a certain type of access that can be granted to a user using OAuth, usually in conjunction with [access tokens](#access-token).
## Search
A Backstage plugin that provides a framework for searching a Backstage [app](#app), including the [Software Catalog](#Software-Catalog) and [TechDocs](#TechDocs). A core feature of Backstage.
## Search Engine (Backstage search)
Existing search technology that [Backstage Search](#search) can take advantage of through its modular design. Lunr is the default search in Backstage Search.
## Software Catalog
A Backstage plugin that provides a framework to keep track of ownership and metadata for any number and type of software [components](#component). A core feature of Backstage.
## Software Templates
A Backstage plugin with which to create [components](#component) in Backstage. A core feature of Backstage. Also known as the scaffolder.
## Software Template
A "skeleton" software project created and managed in the Backstage Software Templates tool.
## System (catalog plugin)
A system is a collection of [entities](#entity) that cooperate to perform a function. A system generally provides one or a few public APIs and consists of a handful of components, resources and private APIs. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
## Task (use cases)
A low-level step-by-step [Procedure](#Procedure).
## TechDocs
A documentation solution that manages and generates a technical documentation from Markdown files stored with software component code. A core feature of Backstage.
## Token
A string containing information.
## Use Case
A purpose for which a [user role](#User-Role) interacts with Backstage. Related to [Objective](#objective): An objective is _what_ the user wants to do; a use case is _how_ the user does it.
## User Role
A class of Backstage user for purposes of analyzing [use cases](#use-case). One of: evaluator; administrator; developer; integrator; and contributor.
docs/references/writing-a-glossary-entry.md
+89
View File
@@ -0,0 +1,89 @@
<!-- This document is meant to solely serve as reference for how to write glossary entries. -->
## Entry format
A glossary entry should consist of two required things and two optional things,
1. a header,
2. a sentence defining what the thing is, and
3. an optional additional sentence or two giving more context into what the thing is and possible pointers on where to find more information, and possibly
4. links out to additional information.
### The header
The header (and first sentence) are the way users will discover your entry. The header has two parts,
1. The actual term, this should be as minimal as possible. You can fit more information into the body of the entry.
2. A disambiguator, this allows users to understand when certain entries are context specific or may have different meanings in different contexts.
### The term
Think of this as a dictionary. Single words are the base units and most definitions refer to a single word. Acronyms are acceptable. An adjective and a noun are also useful, `conditional decision`, `backstage framework`, etc. After 3 or _maybe_ 4 words, you should be trying to simplify and place more content in your entry instead.
In the title, your term should be in Title Case. It should also be in the singular.
### The disambiguator
The goal of a disambiguator is to differentiate terms that may have context specific meanings. This can have two interpretations, either
1. There are multiple terms and we need to create clear boundaries between their contexts, or
2. There are single terms that have meanings that are specific to a single context.
A good example for the first would be resources. Both the catalog plugin and permission plugin have the idea of resources, but they do not refer to the same thing.
A good example for the second would be `Query translators`. In our case, this refers to _search_ query translators, but it may refer to database query translators or the latter. By disambiguating early, we avoid confusion.
Beyond the above advice, there are no strong rules for when or when not to use a disambiguator. It is up to the entry writer and the reviewer.
Your disambiguator should be short, but need not be a single word -- examples include "use cases", "search plugin", "catalog plugin". When used the disambiguator should have the following form, `({disambiguator})` (a parenthesis enclosed term) and will sit to the right of the title. Your disambiguator should use lower case.
### Putting it together
Your title should look like `{word} ({disambiguator})`. Entries are not nested besides the disambiguator and should sit at `##`.
## The first sentence
Your first sentence should include the what for your word. Your goal should be to answer the question, "What is x?". Do _not_ use the word in your first sentence. If you are using other words in the glossary in your definition, you should reference them following [the Referencing section](#referencing).
If you have a term that could mean multiple things in the same context or the context is difficult to add boundaries for, you should separate each meaning into a separate section of the entry using an ordered list. For example,
```md
## Bundle
1. A deployment artifact.
2. A collection of packages.
```
## Additional sentences
You may not be able to fully define what you want in a single sentence. Use more sentences to flush out the meaning; however, if you start to get into the weeds, you should reconsider rehousing that information into a plugin specific "concepts" section. It's okay for words to be duplicated across both if the concepts section adds meaningful technical or architectural discussion.
## Linking out to additional resources
If the term you're defining has a better or more in depth source for that information, link to it. This can include plugin specific concept documents, external documentation, or core framework documentation.
You should format these links as
```md
See [the glossary](./glossary.md) for more details.
```
. Additional links beyond the first one should be appended with `and` or `or` as necessary.
## Putting it all together
```md
## Component (catalog plugin)
A software product that is managed in the Backstage [Software Catalog](#software-catalog). A component can be a service, website, library, data pipeline, or any other piece of software managed as a single project. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
```
## Referencing
### In the glossary
You should reference often. Words are defined recursively, especially in tech and un-nesting some terms requires additional glossary items. It's okay if your terms require multiple other terms to build on. Your goal with referencing is to provide small reusable words that you can trust users know the definition of.
### In the text
You should reference (and create a new entry if it doesn't exist) whenever you see a new word that a reasonable reader may not know. If you've already added a reference in your current passage -- in the glossary this will be your entry -- don't add a new reference. References should point initially to the glossary and if there is additional information (like a concepts page), the glossary should have a link to that page.
docs/releases/v1.23.0-next.1-changelog.md
+3250
View File
File diff suppressed because it is too large Load Diff
docs/releases/v1.23.0-next.2-changelog.md
+3549
View File
File diff suppressed because it is too large Load Diff
docs/tutorials/configuring-plugin-databases.md
+2 -2
View File
@@ -39,10 +39,10 @@ both of them.
```bash
# From your Backstage root directory
# install pg if you need PostgreSQL
yarn add --cwd packages/backend pg
yarn --cwd packages/backend add pg
# install SQLite 3 if you intend to set it as the client
yarn add --cwd packages/backend better-sqlite3
yarn --cwd packages/backend add better-sqlite3
```
From an operational perspective, you only need to install drivers for clients
docs/tutorials/migrate-to-mui5.md
+1 -1
View File
@@ -19,7 +19,7 @@ By default, the `UnifiedThemeProvider` is already used. If you add a custom them
themes: [
{
// ...
provider: ({ children }) => (
Provider: ({ children }) => (
- <ThemeProvider theme={lightTheme}>.
- <CssBaseline>{children}</CssBaseline>.
- </ThemeProvider
docs/tutorials/setup-opentelemetry.md
+2 -1
View File
@@ -18,7 +18,8 @@ The `auto-instrumentations-node` will automatically create spans for code called
```bash
yarn --cwd packages/backend add @opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/sdk-metrics
@opentelemetry/sdk-metrics \
@opentelemetry/sdk-trace-node
```
## Configure
docs/tutorials/switching-sqlite-postgres.md
+1 -1
View File
@@ -21,7 +21,7 @@ First, add PostgreSQL to your `backend` package:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend pg
yarn --cwd packages/backend add pg
```
## Add PostgreSQL configuration