Merge branch 'master' into scaffolder-each
This commit is contained in:
Alex Eftimie
+5
-5
@@ -64,8 +64,8 @@ valuable as you grow.
|
||||
|
||||
### Our company has a strong design language system/brand that we want to incorporate. Does Backstage support this?
|
||||
|
||||
Yes! The Backstage UI is built using Material-UI. With the theming capabilities
|
||||
of Material-UI, you are able to adapt the interface to your brand guidelines.
|
||||
Yes! The Backstage UI is built using Material UI. With the theming capabilities
|
||||
of Material UI, you are able to adapt the interface to your brand guidelines.
|
||||
|
||||
## Technical FAQ
|
||||
|
||||
@@ -73,11 +73,11 @@ of Material-UI, you are able to adapt the interface to your brand guidelines.
|
||||
|
||||
Backstage is a large scale [TypeScript](https://www.typescriptlang.org/)
|
||||
application whose frontend parts use [React](https://react.dev/) and
|
||||
[Material-UI](https://mui.com/), while the backend parts use
|
||||
[Material UI](https://material-ui.com/), while the backend parts use
|
||||
[Node.js](https://nodejs.org/) and the [Express](https://expressjs.com/)
|
||||
framework.
|
||||
|
||||
### Why Material-UI?
|
||||
### Why Material UI?
|
||||
|
||||
The short answer is that's what we've been using in Backstage internally.
|
||||
|
||||
@@ -88,7 +88,7 @@ knew that we would like to use.
|
||||
|
||||
It strikes a good balance between power, customizability, and ease of use. A
|
||||
core focus of Backstage is to make plugin developers productive with as few
|
||||
hurdles as possible. Material-UI lets plugin makers get going easily with both
|
||||
hurdles as possible. Material UI lets plugin makers get going easily with both
|
||||
well-known tech and a large flora of components.
|
||||
|
||||
### What is the end-to-end user flow? The happy path story.
|
||||
|
||||
@@ -20,12 +20,12 @@ In order to provide more flexibility in what types of themes can be used and how
|
||||
they are applied, the `theme` property on the `AppTheme` type is being
|
||||
deprecated and replaced by a `Provider` property instead. The `Provider`
|
||||
property is a React component that will be mounted at the root of the app
|
||||
whenever that theme is active. This also removes the tight connection to MUI and
|
||||
whenever that theme is active. This also removes the tight connection to Material UI and
|
||||
opens up for other type of themes, and removes the hardcoded usage of
|
||||
`<CssBaseline>`.
|
||||
|
||||
To migrate an existing theme, remove the `theme` property and move it over to a
|
||||
new `Provider` component, using `ThemeProvider` from MUI to provide the new
|
||||
new `Provider` component, using `ThemeProvider` from Material UI to provide the new
|
||||
theme, along with `<CssBaseline>`. For example a theme that currently looks like
|
||||
this:
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 210 KiB |
@@ -1,8 +1,7 @@
|
||||
---
|
||||
id: cfaccess
|
||||
id: provider
|
||||
title: Cloudflare Access Provider
|
||||
sidebar_label: cfaccess
|
||||
# prettier-ignore
|
||||
sidebar_label: Cloudflare Access
|
||||
description: Adding Cloudflare Access as an authentication provider in Backstage
|
||||
---
|
||||
|
||||
|
||||
+12
-7
@@ -8,15 +8,16 @@ The authentication system in Backstage serves two distinct purposes: sign-in and
|
||||
identification of users, as well as delegating access to third-party resources. It is possible to
|
||||
configure Backstage to have any number of authentication providers, but only
|
||||
one of these will typically be used for sign-in, with the rest being used to provide
|
||||
access external resources.
|
||||
access to external resources.
|
||||
|
||||
## Built-in Authentication Providers
|
||||
|
||||
Backstage comes with many common authentication providers in the core library:
|
||||
|
||||
- [Atlassian](atlassian/provider.md)
|
||||
- [Auth0](auth0/provider.md)
|
||||
- [Atlassian](atlassian/provider.md)
|
||||
- [Azure](microsoft/provider.md)
|
||||
- [Azure Easy Auth](microsoft/azure-easyauth.md)
|
||||
- [Bitbucket](bitbucket/provider.md)
|
||||
- [Bitbucket Server](bitbucketServer/provider.md)
|
||||
- [Cloudflare Access](cloudflare/access.md)
|
||||
@@ -25,8 +26,8 @@ Backstage comes with many common authentication providers in the core library:
|
||||
- [Google](google/provider.md)
|
||||
- [Google IAP](google/gcp-iap-auth.md)
|
||||
- [Okta](okta/provider.md)
|
||||
- [OAuth 2 Custom Proxy](oauth2-proxy/provider.md)
|
||||
- [OneLogin](onelogin/provider.md)
|
||||
- [OAuth2Proxy](oauth2-proxy/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
|
||||
@@ -71,7 +72,7 @@ both in the frontend app, as well as the `auth` backend plugin. For information
|
||||
on how to configure the backend app, see [Sign-in Identities and Resolvers](./identity-resolver.md).
|
||||
The rest of this section will focus on how to configure sign-in for the frontend app.
|
||||
|
||||
Sign-in is configured by providing a custom `SignInPage` app component. It will
|
||||
Sign-in is configured by providing a custom `SignInPage` app component. It will be
|
||||
rendered before any other routes in the app and is responsible for providing the
|
||||
identity of the current user. The `SignInPage` can render any number of pages and
|
||||
components, or just blank space with logic running in the background. In the end
|
||||
@@ -112,7 +113,8 @@ const app = createApp({
|
||||
```
|
||||
|
||||
You can also use the `providers` prop to enable multiple sign-in methods, for example
|
||||
allows allowing guest access:
|
||||
|
||||
- allowing guest access:
|
||||
|
||||
```tsx title="packages/app/src/App.tsx"
|
||||
const app = createApp({
|
||||
@@ -142,8 +144,11 @@ const app = createApp({
|
||||
|
||||
Some auth providers are so-called "proxy" providers, meaning they're meant to be used
|
||||
behind an authentication proxy. Examples of these are
|
||||
[AWS ALB](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md), [Cloudflare Access](./cloudflare/access.md),
|
||||
[GCP IAP](./google/gcp-iap-auth.md), and [OAuth2 Proxy](./oauth2-proxy/provider.md).
|
||||
[Amazon Application Load Balancer](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md),
|
||||
[Azure EasyAuth](./microsoft/azure-easyauth.md),
|
||||
[Cloudflare Access](./cloudflare/access.md),
|
||||
[Google Identity-Aware Proxy](./google/gcp-iap-auth.md)
|
||||
and [OAuth2 Proxy](./oauth2-proxy/provider.md).
|
||||
|
||||
When using a proxy provider, you'll end up wanting to use a different sign-in page, as
|
||||
there is no need for further user interaction once you've signed in towards the proxy.
|
||||
|
||||
@@ -11,6 +11,14 @@ The Backstage `core-plugin-api` package comes with a Microsoft authentication pr
|
||||
|
||||
Add the following into your `app-config.yaml` or `app-config.production.yaml` file
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
environment: development
|
||||
providers:
|
||||
azure-easyauth:
|
||||
development: {}
|
||||
```
|
||||
|
||||
Add a `providerFactories` entry to the router in
|
||||
`packages/backend/src/plugins/auth.ts`.
|
||||
|
||||
@@ -59,8 +67,10 @@ sign-in mechanism to poll that endpoint through the IAP, on the user's behalf.
|
||||
|
||||
## Frontend Changes
|
||||
|
||||
It is recommended to use the `ProxiedSignInPage` for this provider, which is
|
||||
installed in `packages/app/src/App.tsx` like this:
|
||||
To use this component, you'll need to configure the app's `SignInPage`.
|
||||
It is recommended to use the `ProxiedSignInPage` for this provider when running in Azure, However for local development (or any other scenario running outside of Azure), you'll want to set up something different.
|
||||
For the closest experience to Easy Auth, you could set up the `microsoft` provider locally, but that will requires setting up App Registrations & secrets which may be locked down by your organisation, in which case it may be easier to use guest login locally.
|
||||
See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for more details.
|
||||
|
||||
```tsx title="packages/app/src/App.tsx"
|
||||
/* highlight-add-next-line */
|
||||
@@ -69,17 +79,26 @@ import { ProxiedSignInPage } from '@backstage/core-components';
|
||||
const app = createApp({
|
||||
/* highlight-add-start */
|
||||
components: {
|
||||
SignInPage: props => (
|
||||
<ProxiedSignInPage {...props} provider="azure-easyauth" />
|
||||
),
|
||||
SignInPage: props => {
|
||||
const configApi = useApi(configApiRef);
|
||||
if (configApi.getString('auth.environment') !== 'development') {
|
||||
return <ProxiedSignInPage {...props} provider="azure-easyauth" />;
|
||||
}
|
||||
return (
|
||||
<SignInPage
|
||||
{...props}
|
||||
providers={['guest', 'custom']}
|
||||
title="Select a sign-in method"
|
||||
align="center"
|
||||
/>
|
||||
);
|
||||
},
|
||||
},
|
||||
/* highlight-add-end */
|
||||
// ..
|
||||
});
|
||||
```
|
||||
|
||||
See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information.
|
||||
|
||||
## Azure Configuration
|
||||
|
||||
How to configure azure depends on the service you're enable AAD auth on the app service.
|
||||
|
||||
@@ -101,6 +101,19 @@ export const apis: AnyApiFactory[] = [
|
||||
},
|
||||
environment: configApi.getOptionalString('auth.environment'),
|
||||
defaultScopes: ['openid', 'profile', 'email'],
|
||||
popupOptions: {
|
||||
// optional, used to customize login in popup size
|
||||
size: {
|
||||
fullscreen: true,
|
||||
},
|
||||
/**
|
||||
* or specify popup width and height
|
||||
* size: {
|
||||
width: 1000,
|
||||
height: 1000,
|
||||
}
|
||||
*/
|
||||
},
|
||||
}),
|
||||
}),
|
||||
/* highlight-add-end */
|
||||
@@ -237,6 +250,7 @@ check the App Registration you created:
|
||||
- `metadataUrl`: In Overview > Endpoints tab, grab OpenID Connect metadata document URL.
|
||||
- `authorizationUrl` and `tokenUrl`: Open the `metadataUrl` in a browser, that json will
|
||||
hold these 2 urls somewhere in there.
|
||||
- `tokenEndpointAuthMethod`: Don't define it, use the default unless you know what it does.
|
||||
- `tokenSignedResponseAlg`: Don't define it, use the default unless you know what it does.
|
||||
- `scope`: Only used if we didn't specify `defaultScopes` in the provider's factory,
|
||||
basically the same thing.
|
||||
|
||||
@@ -59,7 +59,7 @@ Just like plugins, modules also have access to services and can depend on their
|
||||
|
||||
A detailed explanation of the package architecture can be found in the
|
||||
[Backstage Architecture
|
||||
Overview](../../overview/architecture-overview.md#package-architecture). The
|
||||
Overview](../../overview/architecture-overview/#package-architecture). The
|
||||
most important packages to consider for this system are the following:
|
||||
|
||||
- `plugin-<pluginId>-backend` houses the implementation of the backend plugins
|
||||
|
||||
@@ -37,4 +37,4 @@ At a high level, when you call `createBackend`, it will create a new backend ins
|
||||
|
||||
Underneath the hood, `createBackend` calls `createSpecializedBackend` from `@backstage/backend-app-api` which is responsible for actually creating the backend instance, but with no services or no features. You can think of `createBackend` more of a 'batteries included' approach, and `createSpecializedBackend` a little more low level.
|
||||
|
||||
As mentioned previously there's also the ability to create multiple of these backends in your project so that you can split apart your backend and deploy different backends that can scale independently of each other. For instance you might choose to deploy a backend with only the catalog plugin enabled, and one with just the scaffolder plugin enabled. We've provided some tools to be able to share services and defaults across your backend system, and you can find out more about that in the [shared environments docs](../building-backends/01-index.md#shared-environments).
|
||||
As mentioned previously there's also the ability to create multiple of these backends in your project so that you can split apart your backend and deploy different backends that can scale independently of each other. For instance you might choose to deploy a backend with only the catalog plugin enabled, and one with just the scaffolder plugin enabled.
|
||||
|
||||
@@ -84,7 +84,7 @@ Options are a simple way to allow for more lightweight customization of a plugin
|
||||
|
||||
The following rules apply to the production setup of Backstage plugins in the broader Backstage plugin ecosystem. Any plugin that is maintained under the `@backstage` package namespace should follow these rules, and it is recommended that all widely distributed plugins follow these rules as well.
|
||||
|
||||
An exception to these rules are made for development or test setups, where shortcuts can be take in order to streamline development and keep things simple.
|
||||
An exception to these rules are made for development or test setups, where shortcuts can be taken in order to streamline development and keep things simple.
|
||||
|
||||
### Scalable
|
||||
|
||||
@@ -92,4 +92,4 @@ Plugins must always be designed to be horizontally scalable. This means that you
|
||||
|
||||
### Isolated
|
||||
|
||||
Plugins must never communicate with each other directly through code, they may only communicate over the network. Plugins that wish to expose an external interface for other plugins and modules to use are recommended to do so though a [node-library](../../local-dev/cli-build-system.md#package-roles) package. The library should export an API client service to make calls to your plugin, or similar construct.
|
||||
Plugins must never communicate with each other directly through code, they may only communicate over the network. Plugins that wish to expose an external interface for other plugins and modules to use are recommended to do so through a [node-library](../../local-dev/cli-build-system.md#package-roles) package. The library should export an API client service to make calls to your plugin, or similar construct.
|
||||
|
||||
@@ -61,11 +61,11 @@ All of these services can be replaced with your own implementations if you need
|
||||
For example, let's say we want to customize the core configuration service to enable remote configuration loading. That would look something like this:
|
||||
|
||||
```ts
|
||||
import { configServiceFactory } from '@backstage/backend-app-api';
|
||||
import { rootConfigServiceFactory } from '@backstage/backend-app-api';
|
||||
|
||||
const backend = createBackend({
|
||||
services: [
|
||||
configServiceFactory({
|
||||
rootConfigServiceFactory({
|
||||
remote: { reloadIntervalSeconds: 60 },
|
||||
}),
|
||||
],
|
||||
@@ -148,35 +148,3 @@ backend.start();
|
||||
```
|
||||
|
||||
We've now split the backend into two separate deployments, but we still need to make sure that they can communicate with each other. This is the hard and somewhat tedious part, as Backstage currently doesn't provide an out of the box solution that solves this. You'll need to manually configure the two backends with custom implementations of the `DiscoveryService` and have them return the correct URLs for each other. Likewise, you'll also need to provide a custom implementation of the `DiscoveryApi` in the frontend, unless you surface the two backends via a proxy that handles the routing instead.
|
||||
|
||||
### Shared Environments
|
||||
|
||||
To make it a bit easier to manage multiple backends, it's possible to create a shared environment that can be used across multiple backends. You would typically house it in a separate package that can be referenced by backends in your monorepo, or published to a package registry for broader use.
|
||||
|
||||
A shared environment contains a set of service implementations that should be used across all backends. These services will override the default ones, but if a service is provided directly to the backend, it will override the one in the shared environment.
|
||||
|
||||
A shared environment is defined using `createSharedEnvironment`. In this example we place it in a new and separate package called `backend-env`:
|
||||
|
||||
```ts
|
||||
// packages/backend-env/src/index.ts
|
||||
import { createSharedEnvironment } from '@backstage/backend-plugin-api';
|
||||
import { customDiscoveryServiceFactory } from './customDiscoveryServiceFactory';
|
||||
|
||||
export const env = createSharedEnvironment({
|
||||
services: [
|
||||
customDiscoveryServiceFactory(), // custom DiscoveryService implementation
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
And passed on to backends using the `env` option:
|
||||
|
||||
```ts
|
||||
// packages/backend-b/src/index.ts, imports omitted
|
||||
import { env } from '@internal/backend-env';
|
||||
|
||||
const backend = createBackend({ env });
|
||||
|
||||
backend.add(scaffolderPlugin());
|
||||
backend.start();
|
||||
```
|
||||
|
||||
@@ -37,7 +37,7 @@ describe('myPlugin', () => {
|
||||
|
||||
const { server } = await startTestBackend({
|
||||
features: [myPlugin()],
|
||||
services: [mockServices.config.factory({ data: fakeConfig })],
|
||||
services: [mockServices.rootConfig.factory({ data: fakeConfig })],
|
||||
});
|
||||
|
||||
const response = await request(server).get('/api/example/get-value');
|
||||
|
||||
@@ -183,11 +183,11 @@ There's additional configuration that you can optionally pass to setup the `conf
|
||||
You can configure these additional options by adding an override for the core service when calling `createBackend` like follows:
|
||||
|
||||
```ts
|
||||
import { configServiceFactory } from '@backstage/backend-app-api';
|
||||
import { rootConfigServiceFactory } from '@backstage/backend-app-api';
|
||||
|
||||
const backend = createBackend({
|
||||
services: [
|
||||
configServiceFactory({
|
||||
rootConfigServiceFactory({
|
||||
argv: [
|
||||
'--config',
|
||||
'/backstage/app-config.development.yaml',
|
||||
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
id: aws-lightsail
|
||||
title: Deploying Backstage on AWS Lightsail
|
||||
sidebar_label: AWS Lightsail
|
||||
description: How to deploy Backstage on AWS Lightsail
|
||||
---
|
||||
|
||||
> **DISCLAIMER: The `deploy` command is in alpha and still experimental. Do not use the `deploy` command for production deployments.**
|
||||
|
||||
Getting started with Backstage often involves setting up an instance on a cloud provider and sharing it with your team so they can experiment. To make this cloud deployment easier, we've built a `deploy` command to stand up a proof-of-concept instance on AWS (using Lightsail).
|
||||
|
||||
## What is AWS Lightsail
|
||||
|
||||
:::tip
|
||||
|
||||
AWS offers a free tier for up to three months on $10 USD/month Container service (Micro -1 node). By default we use the `nano` node, so if you are a new user this approach shouldn't cost you anything. For more information, refer to the [pricing](https://aws.amazon.com/lightsail/pricing/) documentation.
|
||||
|
||||
:::
|
||||
|
||||
AWS Lightsail offers a simple way to run containers in the cloud. To learn more about AWS Lightsail, please refer to the [official documentation](https://lightsail.aws.amazon.com/ls/docs/en_us/articles/amazon-lightsail-container-services-deployments).
|
||||
|
||||
## Creating user in AWS
|
||||
|
||||
- Open the AWS console and navigate to the IAM section
|
||||
- In the left side menu click on `Users` and then click on `Add users`
|
||||
- Specify a username and then click on `Next`
|
||||
- Afterwards you can assign permissions, select `Attach policies directly` and then click on `Create policy`.
|
||||
This should take you to a new window in which you can create a new policy based on `JSON`.
|
||||
Copy over the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "VisualEditor0",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"ecr:DescribeImageReplicationStatus",
|
||||
"ecr:ListTagsForResource",
|
||||
"ecr:UploadLayerPart",
|
||||
"ecr:BatchGetRepositoryScanningConfiguration",
|
||||
"ecr:DeleteRepository",
|
||||
"ecr:GetRegistryScanningConfiguration",
|
||||
"ecr:CompleteLayerUpload",
|
||||
"ecr:TagResource",
|
||||
"ecr:DescribeRepositories",
|
||||
"ecr:DeleteRepositoryPolicy",
|
||||
"ecr:BatchCheckLayerAvailability",
|
||||
"ecr:GetLifecyclePolicy",
|
||||
"ecr:GetRegistryPolicy",
|
||||
"ecr:PutLifecyclePolicy",
|
||||
"ecr:DescribeImageScanFindings",
|
||||
"ecr:GetLifecyclePolicyPreview",
|
||||
"ecr:CreateRepository",
|
||||
"ecr:DescribeRegistry",
|
||||
"ecr:GetDownloadUrlForLayer",
|
||||
"ecr:GetAuthorizationToken",
|
||||
"ecr:DeleteLifecyclePolicy",
|
||||
"ecr:PutImage",
|
||||
"ecr:UntagResource",
|
||||
"ecr:SetRepositoryPolicy",
|
||||
"ecr:BatchGetImage",
|
||||
"ecr:InitiateLayerUpload",
|
||||
"ecr:GetRepositoryPolicy",
|
||||
"lightsail:CreateContainerService",
|
||||
"lightsail:GetKeyPair",
|
||||
"lightsail:GetContainerServiceDeployments",
|
||||
"lightsail:CreateContainerServiceRegistryLogin",
|
||||
"lightsail:GetContainerImages",
|
||||
"lightsail:UntagResource",
|
||||
"lightsail:RegisterContainerImage",
|
||||
"lightsail:GetContainerServices",
|
||||
"lightsail:GetContainerServicePowers",
|
||||
"lightsail:GetKeyPairs",
|
||||
"lightsail:CreateContainerServiceDeployment",
|
||||
"lightsail:GetContainerServiceMetricData",
|
||||
"lightsail:GetContainerAPIMetadata",
|
||||
"lightsail:DeleteContainerService",
|
||||
"lightsail:GetContainerLog",
|
||||
"lightsail:TagResource"
|
||||
],
|
||||
"Resource": "*"
|
||||
},
|
||||
{
|
||||
"Sid": "Statement1",
|
||||
"Effect": "Allow",
|
||||
"Action": [],
|
||||
"Resource": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Then click on `Next` and give the policy a name and a description of your liking. Afterwards, click on `Create policy`.
|
||||
|
||||
- Navigate back to the user creation window and press on the refresh button and search for the policy you just created. Now, create the user.
|
||||
- Now you will be redirected to all users, click on the user you just created and click on `Security credentials`
|
||||
- Scroll below and click on `Create access key`
|
||||
- Choose `Command Line Interface (CLI)`
|
||||
- Now export the following values
|
||||
|
||||
```bash
|
||||
$ export AWS_ACCESS_KEY_ID=... (first value)
|
||||
$ export AWS_SECRET_ACCESS_KEY=.... (second secret value)
|
||||
```
|
||||
|
||||
## Configuring the Pulumi CLI
|
||||
|
||||
Second, install the [Pulumi CLI](https://www.pulumi.com/docs/get-started/install/).
|
||||
|
||||
Then we need to execute the following commands, to set Pulumi up:
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure to store your passphrase somewhere safe as it is used to encrypt/decrypt your Pulumi config.
|
||||
|
||||
:::
|
||||
|
||||
```bash
|
||||
$ pulumi login --local
|
||||
$ export PULUMI_CONFIG_PASSPHRASE="<your-secret>"
|
||||
```
|
||||
|
||||
By using `pulumi login --local` we are making sure that Pulumi stores our state on the local file disk. The environment variable `PULUMI_CONFIG_PASSPHRASE` is used by Pulumi to generate a unique key for your stack
|
||||
|
||||
## Deploying your instance on Lightsail
|
||||
|
||||
:::warning
|
||||
|
||||
Make sure that [Docker](https://docs.docker.com/) is running before you start this section.
|
||||
|
||||
:::
|
||||
|
||||
After you have made your changes to your local instance, it's time to deploy it on Lightsail.
|
||||
|
||||
First, we need to configure a new `app-config` file and update the `baseUrl`.
|
||||
|
||||
```bash
|
||||
$ touch app-config.deployment.yaml
|
||||
```
|
||||
|
||||
And then update the file with the following yaml:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
baseUrl: ${BACKSTAGE_HOST}
|
||||
|
||||
backend:
|
||||
baseUrl: ${BACKSTAGE_HOST}
|
||||
```
|
||||
|
||||
The environment variable `BACKSTAGE_HOST` will be set to the endpoint that AWS Lightsail creates.
|
||||
|
||||
Now we can deploy our instance!
|
||||
|
||||
```bash
|
||||
$ npx backstage-deploy aws --stack backstage-poc --create-dockerfile
|
||||
```
|
||||
|
||||
In the first part of the command, we are specifying that we want to deploy our instance on AWS. With the [`--stack`](https://www.pulumi.com/docs/reference/cli/pulumi_stack/) option, we are providing Pulumi a reference to our container deployment. Furthermore, with the `--create-dockerfile` option, there will be a `Dockerfile` and `.dockerignore` created in the root of the project.
|
||||
|
||||
After running the command, Pulumi will start creating the following resources for you in AWS:
|
||||
|
||||
- ECR Repository
|
||||
- Lightsail Container Service
|
||||
- Lightsail Container Service Deployment
|
||||
- Policy that allows Lightsail to pull from ECR
|
||||
|
||||
If it's the first time building the Docker image, it might take a while for everything to be fully provisioned. After the command is finished running, your Backstage instance should be up and running on AWS Lightsail! 🎉
|
||||
|
||||
### Cleaning up resources
|
||||
|
||||
Cleaning up the resources is also done with the deploy command.
|
||||
|
||||
```bash
|
||||
$ npx backstage-deploy aws --stack backstage-poc --destroy
|
||||
```
|
||||
|
||||
This will delete everything that was originally created by the `deploy` command.
|
||||
+26
-10
@@ -37,7 +37,7 @@ The required steps in the host build are to install dependencies with
|
||||
`yarn install`, generate type definitions using `yarn tsc`, and build the backend
|
||||
package with `yarn build:backend`.
|
||||
|
||||
In a CI workflow it might look something like this:
|
||||
In a CI workflow it might look something like this, from the root:
|
||||
|
||||
```bash
|
||||
yarn install --frozen-lockfile
|
||||
@@ -47,7 +47,7 @@ yarn tsc
|
||||
|
||||
# Build the backend, which bundles it all up into the packages/backend/dist folder.
|
||||
# The configuration files here should match the one you use inside the Dockerfile below.
|
||||
yarn build:backend --config app-config.yaml
|
||||
yarn build:backend --config ../../app-config.yaml
|
||||
```
|
||||
|
||||
Once the host build is complete, we are ready to build our image. The following
|
||||
@@ -56,13 +56,18 @@ Once the host build is complete, we are ready to build our image. The following
|
||||
```Dockerfile
|
||||
FROM node:16-bullseye-slim
|
||||
|
||||
# Install isolate-vm dependencies, these are needed by the @backstage/plugin-scaffolder-backend.
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
--mount=type=cache,target=/var/lib/apt,sharing=locked \
|
||||
apt-get update && \
|
||||
apt-get install -y --no-install-recommends python3 g++ build-essential && \
|
||||
yarn config set python /usr/bin/python3
|
||||
|
||||
# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
|
||||
# in which case you should also move better-sqlite3 to "devDependencies" in package.json.
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
--mount=type=cache,target=/var/lib/apt,sharing=locked \
|
||||
apt-get update && \
|
||||
apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \
|
||||
yarn config set python /usr/bin/python3
|
||||
apt-get install -y --no-install-recommends libsqlite3-dev
|
||||
|
||||
# From here on we use the least-privileged `node` user to run the backend.
|
||||
USER node
|
||||
@@ -169,13 +174,19 @@ RUN find packages \! -name "package.json" -mindepth 2 -maxdepth 2 -exec rm -rf {
|
||||
# Stage 2 - Install dependencies and build packages
|
||||
FROM node:16-bullseye-slim AS build
|
||||
|
||||
# install sqlite3 dependencies
|
||||
# Install isolate-vm dependencies, these are needed by the @backstage/plugin-scaffolder-backend.
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
--mount=type=cache,target=/var/lib/apt,sharing=locked \
|
||||
apt-get update && \
|
||||
apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \
|
||||
apt-get install -y --no-install-recommends python3 g++ build-essential && \
|
||||
yarn config set python /usr/bin/python3
|
||||
|
||||
# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
|
||||
# in which case you should also move better-sqlite3 to "devDependencies" in package.json.
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
--mount=type=cache,target=/var/lib/apt,sharing=locked \
|
||||
apt-get install -y --no-install-recommends libsqlite3-dev
|
||||
|
||||
USER node
|
||||
WORKDIR /app
|
||||
|
||||
@@ -200,13 +211,18 @@ RUN mkdir packages/backend/dist/skeleton packages/backend/dist/bundle \
|
||||
# Stage 3 - Build the actual backend image and install production dependencies
|
||||
FROM node:16-bullseye-slim
|
||||
|
||||
# Install isolate-vm dependencies, these are needed by the @backstage/plugin-scaffolder-backend.
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
--mount=type=cache,target=/var/lib/apt,sharing=locked \
|
||||
apt-get update && \
|
||||
apt-get install -y --no-install-recommends python3 g++ build-essential && \
|
||||
yarn config set python /usr/bin/python3
|
||||
|
||||
# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
|
||||
# in which case you should also move better-sqlite3 to "devDependencies" in package.json.
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
--mount=type=cache,target=/var/lib/apt,sharing=locked \
|
||||
apt-get update && \
|
||||
apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \
|
||||
yarn config set python /usr/bin/python3
|
||||
apt-get install -y --no-install-recommends libsqlite3-dev
|
||||
|
||||
# From here on we use the least-privileged `node` user to run the backend.
|
||||
USER node
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: koyeb
|
||||
title: Deploying with Koyeb
|
||||
sidebar_label: Koyeb
|
||||
description: How to deploy Backstage to Koyeb
|
||||
---
|
||||
|
||||
This guide explains how to deploy Backstage to [Koyeb](https://www.koyeb.com/), a serverless platform that provides the fastest way to deploy applications globally. Koyeb supports git-driven and container-based deployments.
|
||||
|
||||
Before you begin, make sure you have a [Koyeb account](https://app.koyeb.com/) to follow this guide.
|
||||
|
||||
## Configuring the CLI
|
||||
|
||||
First, install the
|
||||
[Koyeb CLI](https://www.koyeb.com/docs/quickstart/koyeb-cli) and follow the instructions in the [quickstart guide](https://www.koyeb.com/docs/quickstart/koyeb-cli) to login.
|
||||
|
||||
Then, configure your `app-config.yaml` with your `baseUrl`:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
# Should be the same as backend.baseUrl when using the `app-backend` plugin
|
||||
baseUrl: https://<your-app>.koyeb.app
|
||||
|
||||
backend:
|
||||
baseUrl: https://<your-app>.koyeb.app
|
||||
listen:
|
||||
# The $PORT environment variable is a feature of Koyeb
|
||||
# https://www.koyeb.com/docs/apps/services
|
||||
port: ${PORT]
|
||||
```
|
||||
|
||||
## Push and deploy Backstage to Koyeb
|
||||
|
||||
Push your Backstage application with its [Dockerfile](docker.md) to Koyeb using the following command:
|
||||
|
||||
```bash
|
||||
koyeb app init example-backstage \
|
||||
--git github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> \
|
||||
--git-branch main \
|
||||
--ports 8000:http \
|
||||
--routes /:8000 \
|
||||
--env PORT=8000
|
||||
```
|
||||
|
||||
Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with `.koyeb.app`.
|
||||
|
||||
Congratulations! Now you should have Backstage up and running! 🎉
|
||||
@@ -7,7 +7,7 @@ description: Documentation on Design
|
||||
Be it a new component contribution, or plugin specific components, you'll want
|
||||
to follow these guidelines. We'll cover the three main subjects that define the
|
||||
general look and feel of your components, all of which build on top of the
|
||||
Material-UI theme features:
|
||||
Material UI theme features:
|
||||
|
||||
- Layout
|
||||
- Color palette
|
||||
@@ -17,10 +17,10 @@ Material-UI theme features:
|
||||
|
||||
Layout refers to how you organize or stack content. Whenever possible, we want
|
||||
to use Backstage's components (check the [Storybook][1] for a list and demo)
|
||||
first, and otherwise fall back to Material-UI components (check the [MUI docs][2]).
|
||||
first, and otherwise fall back to Material UI components (check the [Material UI docs][2]).
|
||||
|
||||
If none of these fit your layout needs, then you can build your own components.
|
||||
However, using HTML+CSS directly is not recommended; it's better to use MUI
|
||||
However, using HTML+CSS directly is not recommended; it's better to use Material UI
|
||||
layout components to make your layout theme aware, meaning if someone changes
|
||||
the theme, your layout would react to those changes without requiring updates
|
||||
to your code.
|
||||
@@ -43,13 +43,13 @@ specific styles for that component, that includes paddings, margins and colors.
|
||||
|
||||
However when making a component from scratch you'll need to reference the theme
|
||||
as much as possible, make sure to use the theme's color palette. Most Backstage
|
||||
components and all MUI components should use the theme's color palette by default,
|
||||
components and all Material UI components should use the theme's color palette by default,
|
||||
so unless you need explicit control on the color of a component (say when the
|
||||
component was designed to use the primary color but you want to use the
|
||||
secondary color instead), then the easiest way to access the color palette is
|
||||
to [Override the Component Styles][11] as suggested by Backstage.
|
||||
|
||||
It's not a very common use case to override a theme color in a MUI component
|
||||
It's not a very common use case to override a theme color in a Material UI component
|
||||
but let's say you have a custom Sidebar component with a Paper component that
|
||||
highlights its content with a different color for a side menu or something
|
||||
(usually you use the elevation, but maybe the designer wanted a colorful app).
|
||||
@@ -78,7 +78,7 @@ which tokens you can use as reference from the compiled theme.
|
||||
|
||||
## Typography
|
||||
|
||||
Most of the time the components from MUI will use the `<Typography />` component
|
||||
Most of the time the components from Material UI will use the `<Typography />` component
|
||||
which will use the theme's typography properties like font family, size, weight
|
||||
and appropriate color from the palette for the context of that component. This applies for example to
|
||||
buttons that use white font color for contained buttons, or the respective color
|
||||
|
||||
@@ -14,8 +14,8 @@ You'll find our storybook at
|
||||
[http://backstage.io/storybook](http://backstage.io/storybook).
|
||||
|
||||
As noted in the [design introduction](design.md), Backstage's design is based
|
||||
off of [Material-UI](https://material-ui.com/). Much of the UI elements use
|
||||
direct Material-UI, while we've also extended and written custom ones to provide
|
||||
off of [Material UI](https://material-ui.com/). Much of the UI elements use
|
||||
direct Material UI, while we've also extended and written custom ones to provide
|
||||
specific functionality.
|
||||
|
||||
|
||||
@@ -27,13 +27,13 @@ copied.
|
||||
When custom Backstage components are created, they are placed in the
|
||||
`@backstage/core-components` package and added to the Storybook.
|
||||
|
||||
There may be times where an existing Material-UI component (in
|
||||
There may be times where an existing Material UI component (in
|
||||
`@material-ui/core`) is sufficient and doesn't need to be wrapped or duplicated.
|
||||
However, we may want to identify an _opinionated_ way to use that component
|
||||
inside of Backstage. In these cases, stories showing how to use those existing
|
||||
components will also be put into our storybook.
|
||||
|
||||
When a story example using Material-UI becomes more complex, requiring a
|
||||
When a story example using Material UI becomes more complex, requiring a
|
||||
specific set of colors, variants, parameters, etc., it may become a candidate to
|
||||
be refactored to become a full Backstage core component.
|
||||
|
||||
|
||||
@@ -110,7 +110,7 @@ cluster. Valid values are:
|
||||
| `google` | This will use a user's Google access token from the [Google auth provider](https://backstage.io/docs/auth/google/provider) to access the Kubernetes API on GKE clusters. |
|
||||
| `googleServiceAccount` | This will use the Google Cloud service account credentials to access resources in clusters |
|
||||
| `oidc` | This will use [Oidc Tokens](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens) to authenticate to the Kubernetes API. When this is used the `oidcTokenProvider` field should also be set. Please note the cluster must support OIDC, at the time of writing AKS clusters do not support OIDC. |
|
||||
| `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set. |
|
||||
| `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set, or else Backstage should be running in-cluster. |
|
||||
|
||||
Check the [Kubernetes Authentication][4] section for additional explanation.
|
||||
|
||||
@@ -127,14 +127,54 @@ CPU/Memory for pods returned by the API server. Defaults to `false`.
|
||||
##### `clusters.\*.serviceAccountToken` (optional)
|
||||
|
||||
The service account token to be used when using the `serviceAccount` auth
|
||||
provider. You could get the service account token with:
|
||||
provider. Note that, unless you have an effective credential rotation procedure
|
||||
in place or have a single Kubernetes cluster running both Backstage and all your
|
||||
services, this auth provider is probably not ideal for production.
|
||||
|
||||
```sh
|
||||
kubectl -n <NAMESPACE> get secret $(kubectl -n <NAMESPACE> get sa <SERVICE_ACCOUNT_NAME> -o=json \
|
||||
| jq -r '.secrets[0].name') -o=json \
|
||||
| jq -r '.data["token"]' \
|
||||
| base64 --decode
|
||||
```
|
||||
Assuming you have already created a service account named `SERVICE_ACCOUNT_NAME`
|
||||
in namespace `NAMESPACE` and it has adequate
|
||||
[permissions](#role-based-access-control), here are some sample procedures to
|
||||
procure a long-lived service account token for use with this provider:
|
||||
|
||||
- On versions of Kubernetes [prior to
|
||||
1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1),
|
||||
you could get an (automatically-generated) token for a service account with:
|
||||
|
||||
```sh
|
||||
kubectl -n <NAMESPACE> get secret $(kubectl -n <NAMESPACE> get sa <SERVICE_ACCOUNT_NAME> -o=json \
|
||||
| jq -r '.secrets[0].name') -o=json \
|
||||
| jq -r '.data["token"]' \
|
||||
| base64 --decode
|
||||
```
|
||||
|
||||
- For Kubernetes 1.24+, as described in [this
|
||||
guide](https://kubernetes.io/docs/concepts/configuration/secret/#service-account-token-secrets),
|
||||
you can obtain a long-lived token by creating a secret:
|
||||
|
||||
```sh
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: <SECRET_NAME>
|
||||
namespace: <NAMESPACE>
|
||||
annotations:
|
||||
kubernetes.io/service-account.name: <SERVICE_ACCOUNT_NAME>
|
||||
type: kubernetes.io/service-account-token
|
||||
EOF
|
||||
```
|
||||
|
||||
waiting for the token controller to populate a token, and retrieving it with:
|
||||
|
||||
```sh
|
||||
kubectl -n <NAMESPACE> get secret <SECRET_NAME> -o go-template='{{.data.token | base64decode}}'
|
||||
```
|
||||
|
||||
If a cluster has `authProvider: serviceAccount` and the `serviceAccountToken`
|
||||
field is omitted, Backstage will ignore the configured URL and certificate data,
|
||||
instead attempting to access the Kubernetes API via an in-cluster client as in
|
||||
[this
|
||||
example](https://github.com/kubernetes-client/javascript/blob/master/examples/in-cluster.js).
|
||||
|
||||
##### `clusters.\*.oidcTokenProvider` (optional)
|
||||
|
||||
|
||||
@@ -51,7 +51,7 @@ The TechDocs plugin has supported integrations to Search, meaning that it
|
||||
provides a default collator factory ready to be used.
|
||||
|
||||
The purpose of this guide is to walk you through how to register the
|
||||
[DefaultTechDocsCollatorFactory](https://github.com/backstage/backstage/blob/de294ce5c410c9eb56da6870a1fab795268f60e3/plugins/techdocs-backend/src/search/DefaultTechDocsCollatorFactory.ts)
|
||||
[DefaultTechDocsCollatorFactory](https://github.com/backstage/backstage/blob/1adc2c7/plugins/search-backend-module-techdocs/src/collators/DefaultTechDocsCollatorFactory.ts)
|
||||
in your App, so that you can get TechDocs documents indexed.
|
||||
|
||||
If you have been through the
|
||||
@@ -61,10 +61,10 @@ so, you can go ahead and follow this guide - if not, start by going through the
|
||||
getting started guide.
|
||||
|
||||
1. Import the `DefaultTechDocsCollatorFactory` from
|
||||
`@backstage/plugin-techdocs-backend`.
|
||||
`@backstage/plugin-search-backend-module-techdocs`.
|
||||
|
||||
```typescript
|
||||
import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-techdocs-backend';
|
||||
import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-search-backend-module-techdocs';
|
||||
```
|
||||
|
||||
2. If there isn't an existing schedule you'd like to run the collator on, be
|
||||
|
||||
@@ -64,7 +64,7 @@ The recommended approach would be to represent information in catalog-info files
|
||||
|
||||
**Naming strategies:**
|
||||
|
||||
- Ldap: Internal ldap usernames as entity names. e.g., owner: user:myuser or user: my-team-name.
|
||||
- Ldap: Internal ldap usernames as entity names. e.g., owner: user:my-user or user: my-team-name.
|
||||
|
||||
**Ownership strategies:**
|
||||
|
||||
|
||||
@@ -351,7 +351,7 @@ component, like `java` or `go`.
|
||||
|
||||
This field is optional, and currently has no special semantics.
|
||||
|
||||
Each tag must be sequences of `[a-z0-9]` separated by `-`, at most 63 characters
|
||||
Each tag must be sequences of `[a-z0-9:+#]` separated by `-`, at most 63 characters
|
||||
in total.
|
||||
|
||||
### `links` [optional]
|
||||
|
||||
@@ -472,8 +472,9 @@ We also provide a high-level example of what a catalog process for a custom
|
||||
entity might look like:
|
||||
|
||||
```ts
|
||||
import { CatalogProcessor, processingResult } from '@backstage/catalog-backend';
|
||||
import { entityKindSchemaValidator } from '@backstage/catalog-model';
|
||||
import { CatalogProcessor, CatalogProcessorEmit, processingResult } from '@backstage/plugin-catalog-node';
|
||||
import { LocationSpec } from '@backstage/plugin-catalog-common'
|
||||
import { Entity, entityKindSchemaValidator } from '@backstage/catalog-model';
|
||||
|
||||
// For an example of the JSONSchema format and how to use $ref markers to the
|
||||
// base definitions, see:
|
||||
@@ -490,6 +491,11 @@ export class FoobarEntitiesProcessor implements CatalogProcessor {
|
||||
entityKindSchemaValidator(foobarEntityV1alpha1Schema),
|
||||
];
|
||||
|
||||
// Return processor name
|
||||
getProcessorName(): string {
|
||||
return 'FoobarEntitiesProcessor'
|
||||
}
|
||||
|
||||
// validateEntityKind is responsible for signaling to the catalog processing
|
||||
// engine that this entity is valid and should therefore be submitted for
|
||||
// further processing.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
The Backstage platform can be customized by incorporating
|
||||
[existing open source plugins](https://github.com/backstage/backstage/tree/master/plugins),
|
||||
|
||||
@@ -74,3 +74,27 @@ you to the registered component in the catalog:
|
||||
And then you'll also be able to see it in the Catalog View table:
|
||||
|
||||
|
||||
|
||||
## Disable Register Existing Component button
|
||||
|
||||
There could be situations where you would like to disable the
|
||||
`Register Existing Component` button for your users. For example:
|
||||
|
||||
|
||||
|
||||
To do so, you will un-register / remove the `catalogImportPlugin.routes.importPage`
|
||||
from `backstage/packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
const app = createApp({
|
||||
apis,
|
||||
bindRoutes({ bind }) {
|
||||
- bind(scaffolderPlugin.externalRoutes, {
|
||||
- registerComponent: catalogImportPlugin.routes.importPage,
|
||||
- });
|
||||
bind(orgPlugin.externalRoutes, {
|
||||
catalogIndex: catalogPlugin.routes.catalogIndex,
|
||||
});
|
||||
```
|
||||
|
||||
After the change, you should no longer see the button.
|
||||
|
||||
@@ -0,0 +1,332 @@
|
||||
---
|
||||
id: ui-options-examples
|
||||
title: ui:options Examples
|
||||
description: The input props that can be specified under ui:options for different pickers
|
||||
---
|
||||
|
||||
## EntityPicker
|
||||
|
||||
The input props that can be specified under `ui:options` for the `EntityPicker` field extension.
|
||||
|
||||
### `allowArbitraryValues`
|
||||
|
||||
Whether to allow arbitrary user input. Defaults to true.
|
||||
|
||||
`allowArbitraryValues` provides input validation when selecting an entity as the values you enter will correspond to a valid entity.
|
||||
|
||||
- Adding a valid entity with `allowArbitraryValues` as `false`
|
||||
|
||||
```yaml
|
||||
entity:
|
||||
title: Entity
|
||||
type: string
|
||||
description: Entity of the component
|
||||
ui:field: EntityPicker
|
||||
ui:options:
|
||||
allowArbitraryValues: false
|
||||
```
|
||||
|
||||
- Adding an arbitrary entity with `allowArbitraryValues` as `true` (default value)
|
||||
|
||||
```yaml
|
||||
entity:
|
||||
title: Entity
|
||||
type: string
|
||||
description: Entity of the component
|
||||
ui:field: EntityPicker
|
||||
ui:options:
|
||||
allowArbitraryValues: true
|
||||
```
|
||||
|
||||
### `allowedKinds`
|
||||
|
||||
DEPRECATED: Use `catalogFilter` instead.
|
||||
|
||||
### `catalogFilter`
|
||||
|
||||
`catalogFilter` supports filtering options by any field(s) of an entity.
|
||||
|
||||
- Get all entities of kind `Group`
|
||||
|
||||
```yaml
|
||||
entity:
|
||||
title: Entity
|
||||
type: string
|
||||
description: Entity of the component
|
||||
ui:field: EntityPicker
|
||||
ui:options:
|
||||
catalogFilter:
|
||||
- kind: Group
|
||||
```
|
||||
|
||||
- Get entities of kind `Group` and spec.type `team`
|
||||
|
||||
```yaml
|
||||
entity:
|
||||
title: Entity
|
||||
type: string
|
||||
description: Entity of the component
|
||||
ui:field: EntityPicker
|
||||
ui:options:
|
||||
catalogFilter:
|
||||
- kind: Group
|
||||
spec.type: team
|
||||
```
|
||||
|
||||
For the full details on the spec.\* values see [here](../software-catalog/descriptor-format.md#kind-group).
|
||||
|
||||
### `defaultKind`
|
||||
|
||||
The default entity kind.
|
||||
|
||||
```yaml
|
||||
system:
|
||||
title: System
|
||||
type: string
|
||||
description: System of the component
|
||||
ui:field: EntityPicker
|
||||
ui:options:
|
||||
catalogFilter:
|
||||
kind: System
|
||||
defaultKind: System
|
||||
```
|
||||
|
||||
### `defaultNamespace`
|
||||
|
||||
The ID of a namespace that the entity belongs to. The default value is `default`.
|
||||
|
||||
- Listing all entities in the `default` namespace (default value)
|
||||
|
||||
```yaml
|
||||
entity:
|
||||
title: Entity
|
||||
type: string
|
||||
description: Entity of the component
|
||||
ui:field: EntityPicker
|
||||
ui:options:
|
||||
defaultNamespace: default
|
||||
```
|
||||
|
||||
- Listing all entities in the `payment` namespace
|
||||
|
||||
```yaml
|
||||
entity:
|
||||
title: Entity
|
||||
type: string
|
||||
description: Entity of the component
|
||||
ui:field: EntityPicker
|
||||
ui:options:
|
||||
defaultNamespace: payment
|
||||
```
|
||||
|
||||
## `OwnerPicker`
|
||||
|
||||
The input props that can be specified under `ui:options` for the `OwnerPicker` field extension.
|
||||
|
||||
### `allowArbitraryValues`
|
||||
|
||||
Whether to allow arbitrary user input. Defaults to true.
|
||||
|
||||
`allowArbitraryValues` provides input validation when selecting an owner as the values you enter will correspond to a valid owner.
|
||||
|
||||
- Adding a valid owner with `allowArbitraryValues` as `false`
|
||||
|
||||
```yaml
|
||||
owner:
|
||||
title: Owner
|
||||
type: string
|
||||
description: Owner of the component
|
||||
ui:field: OwnerPicker
|
||||
ui:options:
|
||||
allowArbitraryValues: false
|
||||
```
|
||||
|
||||
- Adding an arbitrary owner with `allowArbitraryValues` as `true` (default value)
|
||||
|
||||
```yaml
|
||||
owner:
|
||||
title: Owner
|
||||
type: string
|
||||
description: Owner of the component
|
||||
ui:field: OwnerPicker
|
||||
ui:options:
|
||||
allowArbitraryValues: true
|
||||
```
|
||||
|
||||
### `allowedKinds`
|
||||
|
||||
DEPRECATED: Use `catalogFilter` instead.
|
||||
|
||||
### `catalogFilter`
|
||||
|
||||
`catalogFilter` supports filtering options by any field(s) of an entity.
|
||||
|
||||
- Get all entities of kind `Group`
|
||||
|
||||
```yaml
|
||||
owner:
|
||||
title: Owner
|
||||
type: string
|
||||
description: Owner of the component
|
||||
ui:field: OwnerPicker
|
||||
ui:options:
|
||||
catalogFilter:
|
||||
- kind: Group
|
||||
```
|
||||
|
||||
- Get entities of kind `Group` and spec.type `team`
|
||||
|
||||
```yaml
|
||||
owner:
|
||||
title: Owner
|
||||
type: string
|
||||
description: Owner of the component
|
||||
ui:field: OwnerPicker
|
||||
ui:options:
|
||||
catalogFilter:
|
||||
- kind: Group
|
||||
spec.type: team
|
||||
```
|
||||
|
||||
For the full details on the spec.\* values see [here](../software-catalog/descriptor-format.md#kind-group).
|
||||
|
||||
### `defaultNamespace`
|
||||
|
||||
The ID of a namespace that the owner belongs to. The default value is `default`.
|
||||
|
||||
- Listing owners in the `default` namespace (default value)
|
||||
|
||||
```yaml
|
||||
owner:
|
||||
title: Owner
|
||||
type: string
|
||||
description: Owner of the component
|
||||
ui:field: OwnerPicker
|
||||
ui:options:
|
||||
catalogFilter:
|
||||
- kind: Group
|
||||
defaultNamespace: default
|
||||
```
|
||||
|
||||
- Listing owners in the `payment` namespace
|
||||
|
||||
```yaml
|
||||
owner:
|
||||
title: Owner
|
||||
type: string
|
||||
description: Owner of the component
|
||||
ui:field: OwnerPicker
|
||||
ui:options:
|
||||
catalogFilter:
|
||||
- kind: Group
|
||||
defaultNamespace: payment
|
||||
```
|
||||
|
||||
## RepoUrlPicker
|
||||
|
||||
The input props that can be specified under `ui:options` for the `RepoUrlPicker` field extension.
|
||||
|
||||
### `allowedHosts`
|
||||
|
||||
The `allowedHosts` part should be set to where you wish to enable this template
|
||||
to publish to. And it can be any host that is listed in your integrations'
|
||||
config in `app-config.yaml`.
|
||||
|
||||
- Publish only to repositories from `github.com`
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Location
|
||||
type: string
|
||||
ui:field: RepoUrlPicker
|
||||
ui:options:
|
||||
allowedHosts:
|
||||
- github.com
|
||||
```
|
||||
|
||||
### `allowedOrganizations`
|
||||
|
||||
List of allowed organizations in the given SCM platform. You can restrict the template to publish to a set of organizations.
|
||||
|
||||
- Publish only to repositories from organization `my_organization`
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Location
|
||||
type: string
|
||||
ui:field: RepoUrlPicker
|
||||
ui:options:
|
||||
allowedOrganizations:
|
||||
- my_organization
|
||||
```
|
||||
|
||||
### `allowedProjects`
|
||||
|
||||
List of allowed projects in the given SCM platform. You can restrict the template to publish to a set of projects.
|
||||
|
||||
- Publish only to repositories from project `project_1`
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Location
|
||||
type: string
|
||||
ui:field: RepoUrlPicker
|
||||
ui:options:
|
||||
allowedProjects:
|
||||
- project_1
|
||||
```
|
||||
|
||||
### `allowedRepos`
|
||||
|
||||
List of allowed repos in the given SCM platform. You can restrict the template to publish to a set of repository names.
|
||||
|
||||
- Publish to only `repo_1` and `repo_2` repositories
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Location
|
||||
type: string
|
||||
ui:field: RepoUrlPicker
|
||||
ui:options:
|
||||
allowedRepos:
|
||||
- repo_1
|
||||
- repo_2
|
||||
```
|
||||
|
||||
### `allowedOwners`
|
||||
|
||||
List of allowed owners in the given SCM platform. You can restrict the template to publish to repositories owned by specific users/groups by setting the `allowedOwners` option.
|
||||
|
||||
- Publish to only repositories from owner `owner_1` and `owner_2`
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Location
|
||||
type: string
|
||||
ui:field: RepoUrlPicker
|
||||
ui:options:
|
||||
allowedOwners:
|
||||
- owner_1
|
||||
- owner_2
|
||||
```
|
||||
|
||||
### `requestUserCredentials`
|
||||
|
||||
If defined will request user credentials to auth against the given SCM platform.
|
||||
|
||||
```yaml
|
||||
repoUrl:
|
||||
title: Repository Location
|
||||
type: string
|
||||
ui:field: RepoUrlPicker
|
||||
ui:options:
|
||||
requestUserCredentials:
|
||||
secretsKey: USER_OAUTH_TOKEN
|
||||
additionalScopes:
|
||||
github:
|
||||
- workflow:write
|
||||
```
|
||||
|
||||
`secretsKey` is the key used within the template secrets context to store the credential and `additionalScopes` is any additional permission scopes to request.
|
||||
|
||||
The supported `additionalScopes` values are `gerrit`, `github`, `gitlab`, `bitbucket`, and `azure`.
|
||||
@@ -4,8 +4,8 @@ title: Writing Custom Actions
|
||||
description: How to write your own actions
|
||||
---
|
||||
|
||||
If you're wanting to extend the functionality of the Scaffolder, you can do so
|
||||
by writing custom actions which can be used along side our
|
||||
If you want to extend the functionality of the Scaffolder, you can do so
|
||||
by writing custom actions which can be used alongside our
|
||||
[built-in actions](./builtin-actions.md).
|
||||
|
||||
> Note: When adding custom actions, the actions array will **replace the
|
||||
@@ -65,7 +65,7 @@ The `createTemplateAction` takes an object which specifies the following:
|
||||
- `schema.input` - A `zod` or JSON schema object for input values to your function
|
||||
- `schema.output` - A `zod` or JSON schema object for values which are output from the
|
||||
function using `ctx.output`
|
||||
- `handler` - the actual code which is run part of the action, with a context
|
||||
- `handler` - the actual code which is run as part of the action, with a context
|
||||
|
||||
You can also choose to define your custom action using JSON schema instead of `zod`:
|
||||
|
||||
|
||||
@@ -352,6 +352,8 @@ specific set of repository names. A full example could look like this:
|
||||
- backstage
|
||||
```
|
||||
|
||||
For a list of all possible `ui:options` input props for `RepoUrlPicker`, please visit [here](./ui-options-examples.md#repourlpicker).
|
||||
|
||||
The `RepoUrlPicker` is a custom field that we provide part of the
|
||||
`plugin-scaffolder`. You can provide your own custom fields by
|
||||
[writing your own Custom Field Extensions](./writing-custom-field-extensions.md)
|
||||
@@ -472,6 +474,8 @@ owner:
|
||||
kind: [Group, User]
|
||||
```
|
||||
|
||||
For a list of all possible `ui:options` input props for `OwnerPicker`, please visit [here](./ui-options-examples.md#ownerpicker).
|
||||
|
||||
#### `catalogFilter`
|
||||
|
||||
The `catalogFilter` allow you to filter the list entities using any of the [catalog api filters](https://backstage.io/docs/features/software-catalog/software-catalog-api#filtering):
|
||||
|
||||
@@ -507,16 +507,16 @@ folder (/docs) or replace the content in this file.
|
||||
|
||||
Done! You now have support for TechDocs in your own software template!
|
||||
|
||||
## how to enable iframes in TechDocs
|
||||
## How to enable iframes in TechDocs
|
||||
|
||||
TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to
|
||||
sanitize HTML and prevent XSS attacks.
|
||||
|
||||
It's possible to allow some iframes based on a list of allowed hosts. To do
|
||||
this, add the allowed hosts in the `techdocs.sanitizer.allowedIframeHosts`
|
||||
configuration of your `app-config.yaml`
|
||||
configuration of your `app-config.yaml`.
|
||||
|
||||
E.g.
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
@@ -525,7 +525,7 @@ techdocs:
|
||||
- drive.google.com
|
||||
```
|
||||
|
||||
This way, all iframes where the host of src attribute is in the
|
||||
This way, all iframes where the host in the src attribute is in the
|
||||
`sanitizer.allowedIframeHosts` list will be displayed.
|
||||
|
||||
## How to add Mermaid support in TechDocs
|
||||
|
||||
@@ -42,7 +42,7 @@ the "Overriding Backstage and Material UI css rules" section below.
|
||||
You can also create a theme from scratch that matches the `BackstageTheme` type
|
||||
exported by [`@backstage/theme`](https://www.npmjs.com/package/@backstage/theme).
|
||||
See the
|
||||
[Material-UI docs on theming](https://material-ui.com/customization/theming/)
|
||||
[Material UI docs on theming](https://material-ui.com/customization/theming/)
|
||||
for more information about how that can be done.
|
||||
|
||||
## Using your Custom Theme
|
||||
@@ -162,7 +162,7 @@ const myTheme = createTheme({
|
||||
```
|
||||
|
||||
For a more complete example of a custom theme including Backstage and
|
||||
Material-UI component overrides, see the [Aperture
|
||||
Material UI component overrides, see the [Aperture
|
||||
theme](https://github.com/backstage/demo/blob/master/packages/app/src/theme/aperture.ts)
|
||||
from the [Backstage demo site](https://demo.backstage.io).
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ yarn add --cwd packages/backend pg
|
||||
```
|
||||
|
||||
Use your favorite editor to open `app-config.yaml` and add your PostgreSQL
|
||||
configuration. in the root directory of your Backstage app using the credentials
|
||||
configuration in the root directory of your Backstage app using the credentials
|
||||
from the previous steps.
|
||||
|
||||
```yaml title="app-config.yaml"
|
||||
@@ -90,10 +90,17 @@ backend:
|
||||
user: ${POSTGRES_USER}
|
||||
password: ${POSTGRES_PASSWORD}
|
||||
# https://node-postgres.com/features/ssl
|
||||
# ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
|
||||
#ca: # if you have a CA file and want to verify it you can uncomment this section
|
||||
#$file: <file-path>/ca/server.crt
|
||||
# highlight-add-end
|
||||
# ssl:
|
||||
# host is only needed if the connection name differs from the certificate name.
|
||||
# This is for example the case with CloudSQL.
|
||||
# host: servername in the certificate
|
||||
# ca:
|
||||
# $file: <file-path>/server.pem
|
||||
# key:
|
||||
# $file: <file-path>/client.key
|
||||
# cert:
|
||||
# $file: <file-path>/client-cert.pem
|
||||
# highlight-add-end
|
||||
```
|
||||
|
||||
You'll use the connection details from the previous step. You can either set the
|
||||
|
||||
@@ -84,7 +84,7 @@ For example, if you install the `api-docs` plugin, a matching `SidebarItem`
|
||||
could be something like this:
|
||||
|
||||
```tsx title="packages/app/src/components/Root/Root.tsx"
|
||||
// Import icon from MUI
|
||||
// Import icon from Material UI
|
||||
import ExtensionIcon from '@material-ui/icons/Extension';
|
||||
|
||||
// ... inside the AppSidebar component
|
||||
|
||||
@@ -40,7 +40,7 @@ Inside your `packages/app` directory, create a new file where our new homepage c
|
||||
```tsx
|
||||
import React from 'react';
|
||||
|
||||
export const homePage = (
|
||||
export const HomePage = () => (
|
||||
/* We will shortly compose a pretty homepage here. */
|
||||
<h1>Welcome to Backstage!</h1>
|
||||
);
|
||||
|
||||
@@ -53,6 +53,8 @@ create a subdirectory inside your current working directory.
|
||||
npx @backstage/create-app@latest
|
||||
```
|
||||
|
||||
> Note: If this fails on the `yarn install` step, it's likely that you will need to install some additional dependencies which are used to configure `isolated-vm`. You can find out more in their [requirements section](https://github.com/laverdet/isolated-vm#requirements), and then run `yarn install` manually again after you've completed those steps.
|
||||
|
||||
The wizard will ask you for the name of the app, which will also be the name of the directory
|
||||
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ catalog:
|
||||
```
|
||||
|
||||
Finally, register the plugin in `catalog.ts`.
|
||||
For large organizations, this plugin can take a long time, so be careful setting low frequency / timeouts.
|
||||
For large organizations, this plugin can take a long time, so be careful setting low frequency / timeouts and importing a large amount of users / groups for the first try.
|
||||
|
||||
```ts title="packages/backend/src/plugins/catalog.ts"
|
||||
/* highlight-add-next-line */
|
||||
@@ -106,7 +106,7 @@ To grant the managed identity the same permissions as mentioned in _App Registra
|
||||
## Filtering imported Users and Groups
|
||||
|
||||
By default, the plugin will import all users and groups from your directory.
|
||||
This can be customized through [filters](https://learn.microsoft.com/en-us/graph/filter-query-parameter) and [search](https://learn.microsoft.com/en-us/graph/search-query-parameter) queries.
|
||||
This can be customized through [filters](https://learn.microsoft.com/en-us/graph/filter-query-parameter) and [search](https://learn.microsoft.com/en-us/graph/search-query-parameter) queries. Keep in mind that if you omit filters and search queries for the user or group properties, the plugin will automatically import all available users or groups.
|
||||
|
||||
### Groups
|
||||
|
||||
|
||||
@@ -94,7 +94,7 @@ export default async function createPlugin(
|
||||
scheduler: env.scheduler,
|
||||
});
|
||||
env.eventBroker.subscribe(githubProvider);
|
||||
builder.addEntityProvider(demoProvider);
|
||||
builder.addEntityProvider(githubProvider);
|
||||
/* highlight-add-end */
|
||||
const { processingEngine, router } = await builder.build();
|
||||
await processingEngine.start();
|
||||
|
||||
@@ -138,3 +138,4 @@ integration:
|
||||
- `Commit statuses`: `Read-only`
|
||||
- `Variables`: `Read & write` (if templates include GitHub Action Repository Variables)
|
||||
- `Secrets`: `Read & write` (if templates include GitHub Action Repository Secrets)
|
||||
- `Environments`: `Read & write` (if templates include GitHub Environments)
|
||||
|
||||
@@ -23,6 +23,7 @@ catalog:
|
||||
host: gitlab-host # Identifies one of the hosts set up in the integrations
|
||||
branch: main # Optional. Used to discover on a specific branch
|
||||
fallbackBranch: main # Optional. Fallback to be used if there is no default branch configured at the Gitlab repository. It is only used, if `branch` is undefined. Uses `master` as default
|
||||
skipForkedRepos: false # Optional. If the project is a fork, skip repository
|
||||
group: example-group # Optional. Group and subgroup (if needed) to look for repositories. If not present the whole instance will be scanned
|
||||
entityFilename: catalog-info.yaml # Optional. Defaults to `catalog-info.yaml`
|
||||
projectPattern: '[\s\S]*' # Optional. Filters found projects based on provided patter. Defaults to `[\s\S]*`, which means to not filter anything
|
||||
|
||||
@@ -11,6 +11,40 @@ groups -- directly from GitLab. The result is a hierarchy of
|
||||
[`Group`](../../features/software-catalog/descriptor-format.md#kind-group)
|
||||
entities that mirrors your org setup.
|
||||
|
||||
As this provider is not one of the default providers, you will first need to install the Gitlab provider plugin:
|
||||
|
||||
```bash
|
||||
# From your Backstage root directory
|
||||
yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-gitlab
|
||||
```
|
||||
|
||||
Then add the plugin to the plugin catalog `packages/backend/src/plugins/catalog.ts`:
|
||||
|
||||
```ts
|
||||
/* packages/backend/src/plugins/catalog.ts */
|
||||
/* highlight-add-next-line */
|
||||
import { GitlabOrgDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
|
||||
|
||||
const builder = await CatalogBuilder.create(env);
|
||||
/** ... other processors and/or providers ... */
|
||||
/* highlight-add-start */
|
||||
builder.addEntityProvider(
|
||||
...GitlabOrgDiscoveryEntityProvider.fromConfig(env.config, {
|
||||
logger: env.logger,
|
||||
// optional: alternatively, use scheduler with schedule defined in app-config.yaml
|
||||
schedule: env.scheduler.createScheduledTaskRunner({
|
||||
frequency: { minutes: 30 },
|
||||
timeout: { minutes: 3 },
|
||||
}),
|
||||
}),
|
||||
);
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
To use the entity provider, you'll need a [Gitlab integration set up](https://backstage.io/docs/integrations/gitlab/locations).
|
||||
|
||||
```yaml
|
||||
integrations:
|
||||
gitlab:
|
||||
|
||||
@@ -484,30 +484,30 @@ of the build system, including the bundling, tests, builds, and type checking.
|
||||
Loaders are always selected based on the file extension. The following is a list
|
||||
of all supported file extensions:
|
||||
|
||||
| Extension | Exports | Purpose |
|
||||
| ----------- | --------------- | ----------------------------------------------------------------------------- |
|
||||
| `.ts` | Script Module | TypeScript |
|
||||
| `.tsx` | Script Module | TypeScript and XML |
|
||||
| `.js` | Script Module | JavaScript |
|
||||
| `.jsx` | Script Module | JavaScript and XML |
|
||||
| `.mjs` | Script Module | ECMAScript Module |
|
||||
| `.cjs` | Script Module | CommonJS Module |
|
||||
| `.json` | JSON Data | JSON Data |
|
||||
| `.yml` | JSON Data | YAML Data |
|
||||
| `.yaml` | JSON Data | YAML Data |
|
||||
| `.css` | classes | Style sheet |
|
||||
| `.eot` | URL Path | Font |
|
||||
| `.ttf` | URL Path | Font |
|
||||
| `.woff2` | URL Path | Font |
|
||||
| `.woff` | URL Path | Font |
|
||||
| `.bmp` | URL Path | Image |
|
||||
| `.gif` | URL Path | Image |
|
||||
| `.jpeg` | URL Path | Image |
|
||||
| `.jpg` | URL Path | Image |
|
||||
| `.png` | URL Path | Image |
|
||||
| `.svg` | URL Path | Image |
|
||||
| `.md` | URL Path | Markdown File |
|
||||
| `.icon.svg` | React Component | SVG converted into a [MUI SvgIcon](https://mui.com/components/icons/#svgicon) |
|
||||
| Extension | Exports | Purpose |
|
||||
| ----------- | --------------- | -------------------------------------------------------------------------------------- |
|
||||
| `.ts` | Script Module | TypeScript |
|
||||
| `.tsx` | Script Module | TypeScript and XML |
|
||||
| `.js` | Script Module | JavaScript |
|
||||
| `.jsx` | Script Module | JavaScript and XML |
|
||||
| `.mjs` | Script Module | ECMAScript Module |
|
||||
| `.cjs` | Script Module | CommonJS Module |
|
||||
| `.json` | JSON Data | JSON Data |
|
||||
| `.yml` | JSON Data | YAML Data |
|
||||
| `.yaml` | JSON Data | YAML Data |
|
||||
| `.css` | classes | Style sheet |
|
||||
| `.eot` | URL Path | Font |
|
||||
| `.ttf` | URL Path | Font |
|
||||
| `.woff2` | URL Path | Font |
|
||||
| `.woff` | URL Path | Font |
|
||||
| `.bmp` | URL Path | Image |
|
||||
| `.gif` | URL Path | Image |
|
||||
| `.jpeg` | URL Path | Image |
|
||||
| `.jpg` | URL Path | Image |
|
||||
| `.png` | URL Path | Image |
|
||||
| `.svg` | URL Path | Image |
|
||||
| `.md` | URL Path | Markdown File |
|
||||
| `.icon.svg` | React Component | SVG converted into a [Material UI SvgIcon](https://mui.com/material-ui/icons/#svgicon) |
|
||||
|
||||
## Jest Configuration
|
||||
|
||||
|
||||
@@ -10,55 +10,64 @@ and where to use them.
|
||||
## help
|
||||
|
||||
This command displays a help summary or detailed help screens for each command.
|
||||
Below is a cleaned up output of `yarn backstage-cli --help`
|
||||
Below is a cleaned up output of `yarn backstage-cli --help`:
|
||||
|
||||
```text
|
||||
repo [command] Command that run across an entire Backstage project
|
||||
package [command] Lifecycle scripts for individual packages
|
||||
migrate [command] Migration utilities
|
||||
|
||||
create Open up an interactive guide to creating new things in your app
|
||||
|
||||
config:docs Browse the configuration reference documentation
|
||||
config:print Print the app configuration for the current package
|
||||
config:check Validate that the given configuration loads and matches schema
|
||||
config:schema Dump the app configuration schema
|
||||
|
||||
versions:bump Bump Backstage packages to the latest versions
|
||||
versions:check Check Backstage package versioning
|
||||
|
||||
build-workspace Builds a temporary dist workspace from the provided packages
|
||||
create-github-app Create new GitHub App in your organization (experimental)
|
||||
|
||||
info Show helpful information for debugging and reporting bugs
|
||||
help [command] display help for command
|
||||
new [options] Open up an interactive guide to creating new things in
|
||||
your app
|
||||
test Run tests, forwarding args to Jest, defaulting to watch
|
||||
mode [DEPRECATED]
|
||||
config:docs [options] Browse the configuration reference documentation
|
||||
config:print [options] Print the app configuration for the current package
|
||||
config:check [options] Validate that the given configuration loads and matches
|
||||
schema
|
||||
config:schema [options] Print configuration schema
|
||||
repo [command] Command that run across an entire Backstage project
|
||||
package [command] Lifecycle scripts for individual packages
|
||||
migrate [command] Migration utilities
|
||||
versions:bump [options] Bump Backstage packages to the latest versions
|
||||
versions:check [options] Check Backstage package versioning
|
||||
clean Delete cache directories [DEPRECATED]
|
||||
build-workspace <workspace-dir> [packages...] Builds a temporary dist workspace from the provided
|
||||
packages
|
||||
create-github-app <github-org> Create new GitHub App in your organization.
|
||||
info Show helpful information for debugging and reporting bugs
|
||||
help [command] display help for command
|
||||
```
|
||||
|
||||
The `package` command category, `yarn backstage-cli package --help`
|
||||
The `package` command category, `yarn backstage-cli package --help`:
|
||||
|
||||
```text
|
||||
start [options] Start a package for local development
|
||||
build [options] Build a package for production deployment or publishing
|
||||
lint [options] Lint a package
|
||||
test Run tests, forwarding args to Jest, defaulting to watch mode
|
||||
clean Delete cache directories
|
||||
prepack Prepares a package for packaging before publishing
|
||||
postpack Restores the changes made by the prepack command
|
||||
start [options] Start a package for local development
|
||||
build [options] Build a package for production deployment or publishing
|
||||
lint [options] [directories...] Lint a package
|
||||
test Run tests, forwarding args to Jest, defaulting to watch mode
|
||||
clean Delete cache directories
|
||||
prepack Prepares a package for packaging before publishing
|
||||
postpack Restores the changes made by the prepack command
|
||||
help [command] display help for command
|
||||
```
|
||||
|
||||
The `repo` command category, `yarn backstage-cli repo --help`
|
||||
The `repo` command category, `yarn backstage-cli repo --help`:
|
||||
|
||||
```text
|
||||
build [options] Build packages in the project, excluding bundled app and backend packages.
|
||||
lint [options] Lint all packages in the project
|
||||
build [options] Build packages in the project, excluding bundled app and backend packages.
|
||||
lint [options] Lint all packages in the project
|
||||
clean Delete cache and output directories
|
||||
list-deprecations [options] List deprecations
|
||||
test [options] Run tests, forwarding args to Jest, defaulting to watch mode
|
||||
help [command] display help for command
|
||||
```
|
||||
|
||||
The `migrate` command category, `yarn backstage-cli migrate --help`
|
||||
The `migrate` command category, `yarn backstage-cli migrate --help`:
|
||||
|
||||
```text
|
||||
package-roles Add package role field to packages that don't have it
|
||||
package-scripts Set package scripts according to each package role
|
||||
package-exports Synchronize package subpath export definitions
|
||||
package-lint-configs Migrates all packages to use @backstage/cli/config/eslint-factory
|
||||
react-router-deps Migrates the react-router dependencies for all packages to be peer dependencies
|
||||
help [command] display help for command
|
||||
```
|
||||
|
||||
## repo build
|
||||
@@ -235,7 +244,7 @@ Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## config:docs
|
||||
## config\:docs
|
||||
|
||||
This commands opens up the reference documentation of your apps local
|
||||
configuration schema in the browser. This is useful to get an overview of what
|
||||
@@ -252,7 +261,7 @@ Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## config:print
|
||||
## config\:print
|
||||
|
||||
Print the static configuration, defaulting to reading `app-config.yaml` in the
|
||||
repo root, using schema collected from all local packages in the repo.
|
||||
@@ -277,7 +286,7 @@ Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## config:check
|
||||
## config\:check
|
||||
|
||||
Validate that static configuration loads and matches schema, defaulting to
|
||||
reading `app-config.yaml` in the repo root and using schema collected from all
|
||||
@@ -296,7 +305,7 @@ Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## config:schema
|
||||
## config\:schema
|
||||
|
||||
Dump the configuration schema that was collected from all local packages in the
|
||||
repo.
|
||||
@@ -315,7 +324,7 @@ Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## versions:bump
|
||||
## versions\:bump
|
||||
|
||||
Bump all `@backstage` packages to the latest versions. This checks for updates
|
||||
in the package registry, and will update entries both in `yarn.lock` and
|
||||
@@ -330,7 +339,7 @@ Options:
|
||||
--release <version|next|main> Bump to a specific Backstage release line or version (default: "main")
|
||||
```
|
||||
|
||||
## versions:check
|
||||
## versions\:check
|
||||
|
||||
Validate `@backstage` dependencies within the repo, making sure that there are
|
||||
no duplicates of packages that might lead to breakages.
|
||||
|
||||
@@ -66,7 +66,7 @@ By default all internal users are allowed to create and delete entities. If this
|
||||
|
||||
## Scaffolder
|
||||
|
||||
By default, Scaffolding jobs execute directly on the host machine, including any actions defined in the template. Because the Scaffolder templates are considered a more sensitive area it is recommended to control access to create and update templates to trusted parties. Template execution is intended to be secure regardless of input, but we still recommend this additional layer of protection. The string templating is executed in a [node VM sandbox](https://github.com/patriksimek/vm2) to mitigate the possibility of remote code execution attacks.
|
||||
By default, Scaffolding jobs execute directly on the host machine, including any actions defined in the template. Because the Scaffolder templates are considered a more sensitive area it is recommended to control access to create and update templates to trusted parties. Template execution is intended to be secure regardless of input, but we still recommend this additional layer of protection. The string templating is executed in a [node VM sandbox](https://github.com/laverdet/isolated-vm) to mitigate the possibility of remote code execution attacks.
|
||||
|
||||
The Scaffolder often has elevated permissions to for example create repositories in a Github organization. The integrator should therefore be cautious of Scaffolder Templates that for example delete or update existing resources as the user input is typically user defined and can therefore delete or modify resources maliciously or by mistake.
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ their own release cadence and versioning policy.
|
||||
|
||||
## Main Release Line
|
||||
|
||||
Release cadence: Monthly
|
||||
Release cadence: Monthly, specifically on the Tuesday before the third Wednesday of each month. The first release took place in March 2022.
|
||||
|
||||
The main release line in versioned with a major, minor and patch version but
|
||||
does **not** adhere to [semver](https://semver.org). The version format is
|
||||
@@ -172,3 +172,13 @@ When we say _Supporting_ a Node.js release, that means the following:
|
||||
- The CI pipeline in the main Backstage repo tests towards the supported releases, and we encourage any other Backstage related projects to do the same.
|
||||
- New Backstage projects created with `@backstage/create-app` will have their `engines.node` version set accordingly.
|
||||
- Dropping compatibility with unsupported releases is not considered a breaking change. This includes using new syntax or APIs, as well as bumping dependencies that drop support for these versions.
|
||||
|
||||
## TypeScript Releases
|
||||
|
||||
The Backstage project uses [TypeScript](https://www.typescriptlang.org/) for type checking within the project, as well as external APIs and documentation. It is important to have a clear policy for which TypeScript versions we support, since we want to be able to adopt new TypeScript features, but at the same time not break existing projects that are using older versions.
|
||||
|
||||
The TypeScript release cadence is roughly every three months. An important aspect of the TypeScript versioning is that it does not follow semver. In particular, there is no differentiation between major and minor versions, both of them are breaking. One way to think about it is to merge the two, for example version 4.7 can be considered major version 47, 5.0 is 50, and so on. Within these releases there can be a number of patch releases, which do follow semver.
|
||||
|
||||
Our policy is to support the last 3 TypeScript versions, for example 4.8, 4.9, and 5.0. Converted to time, this means that we typically support the TypeScript version from the last six to nine months, depending on where in the TypeScript release window we are. This policy applies as a snapshot at the time of any given Backstage release, new TypeScript releases only apply to the following Backstage main-line release, not to the current one.
|
||||
|
||||
For anyone maintaining their own Backstage project, this means that you should strive to bump to the latest TypeScript version at least every 6 months, or you may encounter breakages as you upgrade Backstage packages. If you encounter any issues in doing so, please [file an issue in the main Backstage repository](https://github.com/backstage/backstage/issues/new/choose), as per this policy we should always support the latest version. In order to ensure that we do not start using new TypeScript features too early, the Backstage project itself uses the version at the beginning of the currently supported window, in the above example that would be version 4.8.
|
||||
|
||||
+14
-10
@@ -34,15 +34,19 @@ is a concrete implementation of [AnalyticsApi][analytics-api-type], common
|
||||
integrations are packaged and provided as plugins. Find your analytics tool of
|
||||
choice below.
|
||||
|
||||
| Analytics Tool | Support Status |
|
||||
| ---------------------- | -------------- |
|
||||
| [Google Analytics][ga] | Yes ✅ |
|
||||
| Analytics Tool | Support Status |
|
||||
| ------------------------------------- | -------------- |
|
||||
| [Google Analytics][ga] | Yes ✅ |
|
||||
| [Google Analytics 4][ga4] | Yes ✅ |
|
||||
| [New Relic Browser][newrelic-browser] | Community ✅ |
|
||||
|
||||
To suggest an integration, please [open an issue][add-tool] for the analytics
|
||||
tool your organization uses. Or jump to [Writing Integrations][int-howto] to
|
||||
learn how to contribute the integration yourself!
|
||||
|
||||
[ga]: https://github.com/backstage/backstage/blob/master/plugins/analytics-module-ga/README.md
|
||||
[ga4]: https://github.com/backstage/backstage/blob/master/plugins/analytics-module-ga4/README.md
|
||||
[newrelic-browser]: https://github.com/backstage/backstage/blob/master/plugins/analytics-module-newrelic-browser/README.md
|
||||
[add-tool]: https://github.com/backstage/backstage/issues/new?assignees=&labels=plugin&template=plugin_template.md&title=%5BAnalytics+Module%5D+THE+ANALYTICS+TOOL+TO+INTEGRATE
|
||||
[int-howto]: #writing-integrations
|
||||
[analytics-api-type]: https://backstage.io/docs/reference/core-plugin-api.analyticsapi
|
||||
@@ -52,13 +56,13 @@ learn how to contribute the integration yourself!
|
||||
The following table summarizes events that, depending on the plugins you have
|
||||
installed, may be captured.
|
||||
|
||||
| Action | Subject | Other Notes |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `navigate` | The URL of the page that was navigated to. | The parameters of the current route will be included as attributes |
|
||||
| `click` | The text of the link that was clicked on. | The `to` attribute represents the URL clicked to. |
|
||||
| `create` | The `name` of the software being created; if no `name` property is requested by the given Software Template, then the string `new {templateName}` is used instead. | The context holds an `entityRef`, set to the template's ref (e.g. `template:default/template-name`). |
|
||||
| `search` | The search term entered in any search bar component. | The context holds `searchTypes`, representing `types` constraining the search. The `value` represents the total number of search results for the query. This may not be visible if the permission framework is being used. |
|
||||
| `discover` | The title of the search result that was clicked on | The `value` is the result rank. A `to` attribute is also provided. |
|
||||
| Action | Subject | Other Notes |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `navigate` | The URL of the page that was navigated to. | Fired immediately when route location changes (unless associated plugin/route data is ambiguous, in which case the event is fired after plugin/route data becomes known, immediately before the next event or document unload). The parameters of the current route will be included as attributes. |
|
||||
| `click` | The text of the link that was clicked on. | The `to` attribute represents the URL clicked to. |
|
||||
| `create` | The `name` of the software being created; if no `name` property is requested by the given Software Template, then the string `new {templateName}` is used instead. | The context holds an `entityRef`, set to the template's ref (e.g. `template:default/template-name`). |
|
||||
| `search` | The search term entered in any search bar component. | The context holds `searchTypes`, representing `types` constraining the search. The `value` represents the total number of search results for the query. This may not be visible if the permission framework is being used. |
|
||||
| `discover` | The title of the search result that was clicked on | The `value` is the result rank. A `to` attribute is also provided. |
|
||||
|
||||
If there is an event you'd like to see captured, please [open an
|
||||
issue](https://github.com/backstage/backstage/issues/new?assignees=&labels=enhancement&template=feature_template.md&title=[Analytics%20Event]:%20THE+EVENT+TO+CAPTURE) describing the event you want to see and the questions it
|
||||
|
||||
@@ -16,7 +16,7 @@ browser APIs or by depending on external modules to do the work.
|
||||
- Consider writing plugins in `TypeScript`.
|
||||
- Plan the directory structure of your plugin so that it becomes easy to manage.
|
||||
- Prefer using the [Backstage components](https://backstage.io/storybook),
|
||||
otherwise go with [Material-UI](https://material-ui.com/).
|
||||
otherwise go with [Material UI](https://material-ui.com/).
|
||||
- Check out the shared Backstage APIs before building a new one.
|
||||
|
||||
## Plugin concepts / API
|
||||
|
||||
@@ -36,7 +36,7 @@ Example:
|
||||
```yaml
|
||||
# in app-config.yaml
|
||||
proxy:
|
||||
simple-example: http://simple.example.com:8080
|
||||
/simple-example: http://simple.example.com:8080
|
||||
'/larger-example/v1':
|
||||
target: http://larger.example.com:8080/svc.v1
|
||||
headers:
|
||||
|
||||
@@ -93,7 +93,7 @@ next to them you can split up the UI in as many components as you feel like.
|
||||
|
||||
We have the `ExampleComponent` to show an example Backstage page component. The
|
||||
`ExampleFetchComponent` showcases the common task of making an async request to
|
||||
a public API and plot the response data in a table using Material-UI components.
|
||||
a public API and plot the response data in a table using Material UI components.
|
||||
|
||||
You may tweak these components, rename them and/or replace them completely.
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ This release has an important security fix, along with a lot of squashed bugs an
|
||||
|
||||
### BREAKING: Removed the `Tabs` core component
|
||||
|
||||
The `Tabs` component was removed from `@backstage/core-components`. It was a thin shim that provided very little value and was considered confusing, when the [native Material-UI tabs](https://v4.mui.com/components/tabs/) were already fully usable out of the box. Check out the pull request below for more details.
|
||||
The `Tabs` component was removed from `@backstage/core-components`. It was a thin shim that provided very little value and was considered confusing, when the [native Material UI tabs](https://v4.mui.com/components/tabs/) were already fully usable out of the box. Check out the pull request below for more details.
|
||||
|
||||
Contributed by [@tudi2d](https://github.com/tudi2d) in [#16587](https://github.com/backstage/backstage/pull/16587)
|
||||
|
||||
|
||||
@@ -599,7 +599,7 @@
|
||||
|
||||
- 750e45539ad: Add close button & improve search input.
|
||||
|
||||
MUI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
Material UI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
|
||||
SearchBarBase's TextField's label support added & aria-label uses label string if present, tests relying on the default placeholder value should still work unless custom placeholder was given.
|
||||
|
||||
@@ -641,7 +641,7 @@
|
||||
|
||||
- 750e45539ad: Add close button & improve search input.
|
||||
|
||||
MUI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
Material UI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
|
||||
SearchBarBase's TextField's label support added & aria-label uses label string if present, tests relying on the default placeholder value should still work unless custom placeholder was given.
|
||||
|
||||
|
||||
@@ -175,7 +175,7 @@
|
||||
|
||||
- 750e45539ad: Add close button & improve search input.
|
||||
|
||||
MUI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
Material UI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
|
||||
SearchBarBase's TextField's label support added & aria-label uses label string if present, tests relying on the default placeholder value should still work unless custom placeholder was given.
|
||||
|
||||
@@ -200,7 +200,7 @@
|
||||
|
||||
- 750e45539ad: Add close button & improve search input.
|
||||
|
||||
MUI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
Material UI's Paper wrapping the SearchBar in the SearchPage was removed, we recommend users update their apps accordingly.
|
||||
|
||||
SearchBarBase's TextField's label support added & aria-label uses label string if present, tests relying on the default placeholder value should still work unless custom placeholder was given.
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -4,9 +4,9 @@
|
||||
|
||||
### Minor Changes
|
||||
|
||||
- 1fd38bc4141a: **MUI v5 Support:** Adding platform-wide support for MUI v5 allowing a transition phase for migrating central plugins & components over. We still support v4 instances & plugins by adding a
|
||||
- 1fd38bc4141a: **Material UI v5 Support:** Adding platform-wide support for Material UI v5 allowing a transition phase for migrating central plugins & components over. We still support v4 instances & plugins by adding a
|
||||
|
||||
To allow the future support of plugins & components using MUI v5 you want to upgrade your `AppTheme`'s to using the `UnifiedThemeProvider`
|
||||
To allow the future support of plugins & components using Material UI v5 you want to upgrade your `AppTheme`'s to using the `UnifiedThemeProvider`
|
||||
|
||||
```diff
|
||||
Provider: ({ children }) => (
|
||||
@@ -30,7 +30,7 @@
|
||||
|
||||
### Minor Changes
|
||||
|
||||
- 1fd38bc4141a: Test App Wrapper is now using `UnifiedThemeProvider` for supporting MUI v5 next to MUI v4 in tests.
|
||||
- 1fd38bc4141a: Test App Wrapper is now using `UnifiedThemeProvider` for supporting Material UI v5 next to Material UI v4 in tests.
|
||||
|
||||
### Patch Changes
|
||||
|
||||
@@ -47,9 +47,9 @@
|
||||
|
||||
### Minor Changes
|
||||
|
||||
- 1fd38bc4141a: **MUI v5 Support:** Adding platform-wide support for MUI v5 allowing a transition phase for migrating central plugins & components over. We still support v4 instances & plugins by adding a
|
||||
- 1fd38bc4141a: **Material UI v5 Support:** Adding platform-wide support for Material UI v5 allowing a transition phase for migrating central plugins & components over. We still support v4 instances & plugins by adding a
|
||||
|
||||
To allow the future support of plugins & components using MUI v5 you want to upgrade your `AppTheme`'s to using the `UnifiedThemeProvider`
|
||||
To allow the future support of plugins & components using Material UI v5 you want to upgrade your `AppTheme`'s to using the `UnifiedThemeProvider`
|
||||
|
||||
```diff
|
||||
Provider: ({ children }) => (
|
||||
@@ -234,7 +234,7 @@
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- 20b7da6f1311: Enforcing MUI v5 specific linting to minimize bundle size.
|
||||
- 20b7da6f1311: Enforcing Material UI v5 specific linting to minimize bundle size.
|
||||
- Updated dependencies
|
||||
- @backstage/config-loader@1.3.1-next.0
|
||||
- @backstage/config@1.0.7
|
||||
|
||||
@@ -130,7 +130,7 @@
|
||||
|
||||
- 6b571405f806: `scaffolder/next`: Provide some default template components to `rjsf` to allow for standardization and markdown descriptions
|
||||
- 4505dc3b4598: `scaffolder/next`: Don't render `TemplateGroups` when there's no results in with search query
|
||||
- 6b571405f806: `scaffolder/next`: provide a `ScaffolderField` component which is meant to replace some of the `FormControl` components from MUI, making it easier to write `FieldExtensions`.
|
||||
- 6b571405f806: `scaffolder/next`: provide a `ScaffolderField` component which is meant to replace some of the `FormControl` components from Material UI, making it easier to write `FieldExtensions`.
|
||||
|
||||
### Patch Changes
|
||||
|
||||
@@ -279,7 +279,7 @@
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- 83bdc3a555c1: Replaced usages of `theme.palette.theme.hint` with `theme.palette.text.secondary` as it has been removed in MUI v5
|
||||
- 83bdc3a555c1: Replaced usages of `theme.palette.theme.hint` with `theme.palette.text.secondary` as it has been removed in Material UI v5
|
||||
- Updated dependencies
|
||||
- @backstage/errors@1.2.0-next.0
|
||||
- @backstage/core-plugin-api@1.5.2-next.0
|
||||
@@ -479,7 +479,7 @@
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- 83bdc3a555c1: Replaced usages of `theme.palette.theme.hint` with `theme.palette.text.secondary` as it has been removed in MUI v5
|
||||
- 83bdc3a555c1: Replaced usages of `theme.palette.theme.hint` with `theme.palette.text.secondary` as it has been removed in Material UI v5
|
||||
- Updated dependencies
|
||||
- @backstage/plugin-catalog@1.11.1-next.1
|
||||
- @backstage/core-components@0.13.2-next.1
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,202 @@
|
||||
---
|
||||
id: v1.15.0
|
||||
title: v1.15.0
|
||||
description: Backstage Release v1.15.0
|
||||
---
|
||||
|
||||
These are the release notes for the v1.15.0 release of
|
||||
[Backstage](https://backstage.io/).
|
||||
|
||||
A huge thanks to the whole team of maintainers and contributors as well as the
|
||||
amazing Backstage Community for their hard work in getting this release
|
||||
developed and done.
|
||||
|
||||
## Highlights
|
||||
|
||||
This release has a few important security fixes, along with a lot of squashed
|
||||
bugs and exciting additions as usual! Enjoy.
|
||||
|
||||
### **BREAKING**: Scaffolder build requirements
|
||||
|
||||
The Scaffolder backend uses a sandboxing environment to run its `nunjucks`
|
||||
templating in, for security reasons. This used to leverage the `vm2` library,
|
||||
but in this release it has been replaced by `isolated-vm`. This significantly
|
||||
improves the confidence level in the sandbox implementation since it builds upon
|
||||
`v8` isolates directly. However, it comes with a cost to implementers: it is a
|
||||
native dependency, and as such needs to be built during `yarn` installation, on
|
||||
the exact architecture that it then executes on. For those who compile and run
|
||||
Backstage on stripped-down environments, you will want to ensure that you have
|
||||
the build basics present, e.g. `build-essential` or similar corresponding to
|
||||
your operating system of choice. The `isolated-vm` repo has [some further
|
||||
information](https://github.com/laverdet/isolated-vm#requirements) about the
|
||||
build environment requirements.
|
||||
|
||||
There is a [CVE-2022-39266](https://www.cve.org/CVERecord?id=CVE-2022-39266)
|
||||
that has been reported for `isolated-vm`, which applies only when using
|
||||
`CachedDataOptions`. We do not use that feature at all, since it is recommended
|
||||
against in the [README](https://github.com/laverdet/isolated-vm#shared-options);
|
||||
doing so can lead to breakouts and calling back to the main process. Some
|
||||
security tools may report that this is a vulnerability but it is safe to ignore
|
||||
this through your `.snyk` policy file or similar.
|
||||
|
||||
### **BREAKING**: `@backstage/plugin-linguist-backend`
|
||||
|
||||
There have been some significant updates to the Linguist plugin, in particular
|
||||
the backend and its API. One breaking change is that `LinguistBackendApi` is now
|
||||
an interface rather than a class, and you should create its implementation
|
||||
`LinguistBackendClient` instead.
|
||||
|
||||
Contributed by [@ahhhndre](https://github.com/ahhhndre) in
|
||||
[#16954](https://github.com/backstage/backstage/pull/16954)
|
||||
|
||||
### **BREAKING**: `@backstage/plugin-github-actions`
|
||||
|
||||
In order to make this plugin support GitHub enterprise as well as cloud, its
|
||||
`GithubActionsClient` is updated to take an `scmAuthApi` instead of the previous
|
||||
`githubAuthApi`.
|
||||
|
||||
Contributed by [@koalaty-code](https://github.com/koalaty-code) in
|
||||
[#17781](https://github.com/backstage/backstage/pull/17781)
|
||||
|
||||
### New module: Unprocessed Entities
|
||||
|
||||
This frontend plugin and accompanying backend module lets you peek under the
|
||||
covers of your catalog instance, finding those pesky unprocessed entities that
|
||||
may be stuck in limbo because of an otherwise tricky-to-debug validation issue
|
||||
or similar.
|
||||
|
||||
Check out [the plugin’s
|
||||
README](https://github.com/backstage/backstage/blob/master/plugins/catalog-unprocessed-entities/README.md)
|
||||
for details and installation instructions.
|
||||
|
||||
Contributed by [@alde](https://github.com/alde) in
|
||||
[#17828](https://github.com/backstage/backstage/pull/17828)
|
||||
|
||||
### More movement toward Material UI v5 and React v18 compatibility
|
||||
|
||||
There have been some tweaks here or there to types and the theme system to
|
||||
ensure a smooth future migration toward Material UI version 5. This should be
|
||||
mostly transparent to adopters, but please let us know if you encounter any
|
||||
oddities around the theme system after upgrading to this release.
|
||||
|
||||
To ensure your future compatibility with v5 plugins, you may want to upgrade
|
||||
your theme provider to use the new unified one:
|
||||
|
||||
```diff
|
||||
Provider: ({ children }) => (
|
||||
- <ThemeProvider theme={lightTheme}>
|
||||
- <CssBaseline>{children}</CssBaseline>
|
||||
- </ThemeProvider>
|
||||
+ <UnifiedThemeProvider theme={builtinThemes.light} children={children} />
|
||||
),
|
||||
```
|
||||
|
||||
We’ve also ensured to be more thorough with how we use `PropsWithChildren` to
|
||||
ensure that there’s a smooth transition to the non-implicit children in the
|
||||
React v18 types.
|
||||
|
||||
### New Backend System lifecycle changes
|
||||
|
||||
When using [the new Backend system](https://backstage.io/docs/backend-system/),
|
||||
plugins are now started up concurrently instead of serially. This improves
|
||||
startup times significantly in some cases.
|
||||
|
||||
If you were relying on feature registration order to make sure that one plugin
|
||||
was completely initialized before being consumed by other plugins, we at the
|
||||
same time introduced a new `addStartupHook` method to the
|
||||
`coreServices.lifecycle` that you can use instead to act after all plugin
|
||||
initializations have completed.
|
||||
|
||||
At the same time, the default HTTP server implementation adds a middleware to
|
||||
the top of the chain, which stalls incoming requests for a short period of time
|
||||
while waiting for service startup. If it takes longer than that predefined time,
|
||||
it responds with a `503 Service Unavailable` error. The end result is that as
|
||||
long as startup is typically fast, callers should only see slightly higher
|
||||
turnaround times for requests to services that are starting up, instead of
|
||||
getting 404 errors or similar which was often the case in the past.
|
||||
|
||||
### Azure identity improvements
|
||||
|
||||
On the Azure front, there’s been work toward ensuring support for service
|
||||
principals, managed identities, and workload identities.
|
||||
|
||||
Contributed by [@sanderaernouts](https://github.com/sanderaernouts) in
|
||||
[#17780](https://github.com/backstage/backstage/pull/17780) and
|
||||
[@afscrome](https://github.com/afscrome) in
|
||||
[#18324](https://github.com/backstage/backstage/pull/18324)
|
||||
|
||||
### Resource utilization and error display for k8s pods
|
||||
|
||||
You can now see some resource utilization statistics and errors, where present,
|
||||
for your Kubernetes pods.
|
||||
|
||||
Contributed by [@mclarke47](https://github.com/mclarke47) in
|
||||
[#17563](https://github.com/backstage/backstage/pull/17563) and
|
||||
[#18169](https://github.com/backstage/backstage/pull/18169)
|
||||
|
||||
### Printable TechDocs
|
||||
|
||||
There have been some changes to the TechDocs styles, to properly handle `print`
|
||||
media. This should make PDF exports and printing of documentation work better.
|
||||
Let us know how it goes!
|
||||
|
||||
Contributed by [@maapteh](https://github.com/maapteh) in
|
||||
[#18007](https://github.com/backstage/backstage/pull/18007)
|
||||
|
||||
### OpenAPI linting
|
||||
|
||||
The `backstage-repo-tools` CLI’s OpenAPI features now have a new `lint`
|
||||
subcommand. This lets you automatically lint the OpenAPI schemas of plugins for
|
||||
correctness and best practices.
|
||||
|
||||
Contributed by [@sennyeya](https://github.com/sennyeya) in
|
||||
[#18185](https://github.com/backstage/backstage/pull/18185)
|
||||
|
||||
### Catalog conflict events (experimental)
|
||||
|
||||
If you pass in an event broker to the catalog backend, it now has the
|
||||
experimental ability to emit events onto the event bus describing entity
|
||||
conflicts as they happen internally. This can then be observed and acted upon by
|
||||
external consumers.
|
||||
|
||||
Contributed by [@sblausten](https://github.com/sblausten) in
|
||||
[#16977](https://github.com/backstage/backstage/pull/16977)
|
||||
|
||||
## Security Fixes
|
||||
|
||||
- See the note above about the Scaffolder replacing `vm2` with `isolated-vm`.
|
||||
- There were some cases where sensitive configuration settings could be seen by
|
||||
the browser. The configuration schemas have been tightened up accordingly in a
|
||||
few places to counter this.
|
||||
- The TechDocs base Docker image has been upgraded to include a few security
|
||||
fixes. This will get picked up automatically for future Docker based TechDocs
|
||||
runs, after upgrading Backstage.
|
||||
|
||||
## Upgrade path
|
||||
|
||||
We recommend that you keep your Backstage project up to date with this latest
|
||||
release. For more guidance on how to upgrade, check out the documentation for
|
||||
[keeping Backstage
|
||||
updated](https://backstage.io/docs/getting-started/keeping-backstage-updated).
|
||||
|
||||
## Links and References
|
||||
|
||||
Below you can find a list of links and references to help you learn about and
|
||||
start using this new release.
|
||||
|
||||
- [Backstage official website](https://backstage.io/),
|
||||
[documentation](https://backstage.io/docs/), and [getting started
|
||||
guide](https://backstage.io/docs/getting-started/)
|
||||
- [GitHub repository](https://github.com/backstage/backstage)
|
||||
- Backstage's [versioning and support
|
||||
policy](https://backstage.io/docs/overview/versioning-policy)
|
||||
- [Community Discord](https://discord.gg/backstage-687207715902193673) for
|
||||
discussions and support
|
||||
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.15.0-changelog.md)
|
||||
- Backstage [Demos](https://backstage.io/demos),
|
||||
[Blog](https://backstage.io/blog),
|
||||
[Roadmap](https://backstage.io/docs/overview/roadmap) and
|
||||
[Plugins](https://backstage.io/plugins)
|
||||
|
||||
Sign up for our [newsletter](https://mailchi.mp/spotify/backstage-community) if
|
||||
you want to be informed about what is happening in the world of Backstage.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,87 @@
|
||||
---
|
||||
id: v1.16.0
|
||||
title: v1.16.0
|
||||
description: Backstage Release v1.16.0
|
||||
---
|
||||
|
||||
These are the release notes for the v1.16.0 release of [Backstage](https://backstage.io/).
|
||||
|
||||
A huge thanks to the whole team of maintainers and contributors as well as the amazing Backstage Community for their hard work in getting this release developed and done. A little smaller release this time with the Summer Holidays, hope you’re all having some deserved time off also!
|
||||
|
||||
## Highlights
|
||||
|
||||
### Continued support for Material-UI V5
|
||||
|
||||
There have been some more tweaks here or there to types and the theme system to ensure a smooth future migration toward Material-UI version 5. This should be mostly transparent to adopters, but please let us know if you encounter any oddities around the theme system after upgrading to this release.
|
||||
|
||||
### More plugins support the new Backend System
|
||||
|
||||
There’s been some more plugins that have been ported across to using the new [Backend System](https://backstage.io/docs/backend-system/). They are as follows:
|
||||
|
||||
- `@backstage/plugin-adr-backend` - Contributed by [@angeliski](https://github.com/angeliski) in [#18377](https://github.com/backstage/backstage/pull/18377)
|
||||
- `@backstage/plugin-airbrake-backend` - Contributed by [@anicke](https://github.com/anicke) in [#18598](https://github.com/backstage/backstage/pull/18598)
|
||||
- `@backstage/plugin-azure-devops-backend` - Contributed by [@awanlin](https://github.com/awanlin) in [#18320](https://github.com/backstage/backstage/pull/18320)
|
||||
- `@backstage/plugin-badges-backend` - Contributed by [@awanlin](https://github.com/awanlin) in [#18464](https://github.com/backstage/backstage/pull/18464)
|
||||
- `@backstage/plugin-devtools-backend` - Contributed by [@awanlin](https://github.com/awanlin) in [#18320](https://github.com/backstage/backstage/pull/18320)
|
||||
- `@backstage/plugin-linguist-backend` - Contributed by [@awanlin](https://github.com/awanlin) in [#18320](https://github.com/backstage/backstage/pull/18320)
|
||||
- `@backstage/plugin-entity-feedback-backend` - Contributed by [@anicke](https://github.com/anicke) in [#18361](https://github.com/backstage/backstage/pull/18361)
|
||||
- `@backstage/plugin-lighthouse-backend` - Contributed by [@jroebu14](https://github.com/jroebu14) in [#18633](https://github.com/backstage/backstage/pull/18633)
|
||||
|
||||
Stay tuned for more updates on the future of the Backend System as we move to make this a stable API!
|
||||
|
||||
### **BREAKING**: `@backstage/plugin-catalog-backend-module-incremental-ingestion`
|
||||
|
||||
Incremental event handlers are now async by default, and their response shape has been changed to allow further extension.
|
||||
|
||||
Instead of returning `null` or `undefined` from an event handler to indicate no-oop, instead return the value `{ type: "ignored" }`.
|
||||
|
||||
Contributed by [@cowboyd](https://github.com/cowboyd) in [#18216](https://github.com/backstage/backstage/pull/18216)
|
||||
|
||||
### **BREAKING**: `@backstage/plugin-scaffolder-backend-module-confluence-to-markdown`
|
||||
|
||||
The configuration has been changed and the authentication property of `confluence.auth` is now an `object` instead to allow further evolution.
|
||||
|
||||
Contributed by [@jsundquist](https://github.com/jsundquist) in [#18583](https://github.com/backstage/backstage/pull/18583)
|
||||
|
||||
### `@backstage/plugin-lighthouse`
|
||||
|
||||
Added more verbose component for when no audits for a website corresponding to the provided url were found.
|
||||
|
||||
Contributed by [@Zaperex](https://github.com/Zaperex) in [#18399](https://github.com/backstage/backstage/pull/18399)
|
||||
|
||||
### `@backstage/plugin-home`
|
||||
|
||||
A reference to material-ui’s dependency has been updated from `@rjsf/material-ui` to `@rjsf/material-ui-v5`.
|
||||
|
||||
Contributed by [@mario-mui](https://github.com/mario-mui) in [#18432](https://github.com/backstage/backstage/pull/18432)
|
||||
|
||||
It is now possible to customize the settings widget for different properties by using the`uiSchema` property.
|
||||
|
||||
Contributed by [@ivangonzalezacuna](https://github.com/ivangonzalezacuna) in [#18574](https://github.com/backstage/backstage/pull/18574)
|
||||
|
||||
### `@backstage/plugin-search`
|
||||
|
||||
Fixed bug in `View Full Results` link of Search Modal that did not navigate to the full results page.
|
||||
|
||||
Contributed by [@ciprianna](https://github.com/ciprianna) in [#18407](https://github.com/backstage/backstage/pull/18407)
|
||||
|
||||
## Security Fixes
|
||||
|
||||
This release does not contain any security fixes.
|
||||
|
||||
## Upgrade path
|
||||
|
||||
We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for [keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated).
|
||||
|
||||
## Links and References
|
||||
|
||||
Below you can find a list of links and references to help you learn about and start using this new release.
|
||||
|
||||
- [Backstage official website](https://backstage.io/), [documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/)
|
||||
- [GitHub repository](https://github.com/backstage/backstage)
|
||||
- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy)
|
||||
- [Community Discord](https://discord.gg/backstage-687207715902193673) for discussions and support
|
||||
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.16.0-changelog.md)
|
||||
- Backstage [Demos](https://backstage.io/demos), [Blog](https://backstage.io/blog), [Roadmap](https://backstage.io/docs/overview/roadmap) and [Plugins](https://backstage.io/plugins)
|
||||
|
||||
Sign up for our [newsletter](https://mailchi.mp/spotify/backstage-community) if you want to be informed about what is happening in the world of Backstage.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -995,7 +995,7 @@
|
||||
|
||||
- 64a579a998: Add items prop to SupportButton. This prop can be used to override the items that would otherwise be grabbed from the config.
|
||||
|
||||
- 5d3058355d: Add `react/forbid-elements` linter rule for button, suggest MUI `Button`
|
||||
- 5d3058355d: Add `react/forbid-elements` linter rule for button, suggest Material UI `Button`
|
||||
|
||||
- 3280711113: Updated dependency `msw` to `^0.49.0`.
|
||||
|
||||
@@ -2804,7 +2804,7 @@
|
||||
- d3fea4ae0a: Internal fixes to avoid implicit usage of globals
|
||||
- 2e701b3796: Internal refactor to use `react-router-dom` rather than `react-router`.
|
||||
- a19cffbeed: Update search links to only have header as linkable text
|
||||
- 5d3058355d: Add `react/forbid-elements` linter rule for button, suggest MUI `Button`
|
||||
- 5d3058355d: Add `react/forbid-elements` linter rule for button, suggest Material UI `Button`
|
||||
- 3280711113: Updated dependency `msw` to `^0.49.0`.
|
||||
- 786f1b1419: Support older versions of react-router
|
||||
- Updated dependencies
|
||||
|
||||
@@ -128,11 +128,11 @@ old usages by the `string` type.
|
||||
|
||||
### Constrained `IconComponent` type
|
||||
|
||||
The `IconComponent` type used to allow all of the props from the MUI `SvgIcon`.
|
||||
The `IconComponent` type used to allow all of the props from the Material UI `SvgIcon`.
|
||||
This encouraged some bad patterns in open source plugins such as applying colors
|
||||
to the icons, which in turn hurt the ability to replace the icons with custom
|
||||
ones. The `IconComponent` type, which is now exported from
|
||||
`@backstage/core-plugin-api`, now only accepts a `fontSize` prop used to set the
|
||||
size of the icon. The type is compatible with the MUI `SvgIcon`, but there may
|
||||
size of the icon. The type is compatible with the Material UI `SvgIcon`, but there may
|
||||
be situations where an icon needs an explicit cast to `IconComponent` in order
|
||||
to narrow the type.
|
||||
|
||||
Reference in New Issue
Block a user