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

Merge remote-tracking branch 'origin/master' into update-jest-docs

Browse Source
This commit is contained in:
bnechyporenko
2023-02-13 14:40:25 +01:00
parent 690905b78b f9f63f7d22
commit f2f5c494fa
993 changed files with 25812 additions and 5127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/assets/auth/gcp-iap-jwt-audience-code-popup.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

docs/assets/permissions/permission-framework-overview.drawio.svg
+1 -1
View File
File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 23 KiB

docs/assets/software-catalog/software-model-entities.drawio.svg
Executable → Regular
+1 -1
View File
File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 52 KiB

docs/auth/google/gcp-iap-auth.md
+3 -1
View File
@@ -29,7 +29,9 @@ auth:
jwtHeader: x-custom-header # Optional: Only if you are using a custom header for the IAP JWT
```
You can find the project number and service ID in the Google Cloud Console.
The full `audience` value can be obtained by visiting your [Identity-Aware Proxy Google Cloud console](https://console.cloud.google.com/security/iap), selecting your project, finding your Backend Service to proxy, clicking the 3 vertical dots then "Get JWT Audience Code", and copying from the resulting popup, which will look similar to the following:
![Identity-Aware Proxy JWT Audience Code popup](../../assets/auth/gcp-iap-jwt-audience-code-popup.png)
This config section must be in place for the provider to load at all. Now let's
add the provider itself.
docs/backend-system/architecture/01-index.md
+2
View File
@@ -6,6 +6,8 @@ sidebar_label: System Architecture
description: The structure and architecture of the new Backend System and its component parts
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
## Building Blocks
This section introduces the high-level building blocks upon which this new
docs/backend-system/architecture/02-backends.md
+2
View File
@@ -6,6 +6,8 @@ sidebar_label: Backend
description: Backend instances
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
## The Backend Instance
This is the main entry point for creating a backend. It does not have any functionality in and of itself, but is simply responsible for wiring things together.
docs/backend-system/architecture/03-services.md
+10 -8
View File
@@ -6,6 +6,8 @@ sidebar_label: Services
description: Services for backend plugins
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
Backend services provide shared functionality available to all backend plugins and modules. They are made available through service references that embed a type that represents the service interface, similar to how [Utility APIs](../../api/utility-apis.md) work in the Backstage frontend system. To use a service in your plugin or module you request an implementation of that service using the service reference.
The system surrounding services exists to provide a level of indirection between the service interfaces and their implementation. It is an implementation of dependency injection, where each backend instance is the dependency injection container. The implementation for each service is provided by a service factory, which encapsulates the logic for how each service instance is created.
@@ -59,7 +61,7 @@ class DefaultFooService implements FooService {
}
}
export const fooFactory = createServiceFactory({
export const fooServiceFactory = createServiceFactory({
service: fooServiceRef,
deps: { bar: barServiceRef },
factory({ bar }) {
@@ -73,7 +75,7 @@ To create a service factory we need to provide a reference to the `service` for
If you need the creation of the service instance to be asynchronous, you can make the `factory` function async. For example:
```ts
export const fooFactory = createServiceFactory({
export const fooServiceFactory = createServiceFactory({
service: fooServiceRef,
deps: {},
async factory() {
@@ -92,18 +94,18 @@ To install a service factory in a backend instance, we pass it in through the `s
```ts
const backend = createBackend({
services: [fooFactory()],
services: [fooServiceFactory()],
});
```
Note that we call `fooFactory` to create the service factory instance. This is because `createServiceFactory` always returns a factory function that creates the actual service factory. This is done to always allow for options to be added to the service factory in the future, without breaking existing code. To add options to your service factory, you wrap the object passed to `createServiceFactory` in a callback that accepts the desired options. For example:
Note that we call `fooServiceFactory` to create the service factory instance. This is because `createServiceFactory` always returns a factory function that creates the actual service factory. This is done to always allow for options to be added to the service factory in the future, without breaking existing code. To add options to your service factory, you wrap the object passed to `createServiceFactory` in a callback that accepts the desired options. For example:
```ts
export interface FooFactoryOptions {
mode: 'eager' | 'lazy';
}
export const fooFactory = createServiceFactory(
export const fooServiceFactory = createServiceFactory(
(options?: FooFactoryOptions) => ({
service: fooServiceRef,
deps: { bar: barServiceRef },
@@ -118,7 +120,7 @@ This lets us use the options to customize the factory implementation in any way
```ts
const backend = createBackend({
services: [fooFactory({ mode: 'eager' })],
services: [fooServiceFactory({ mode: 'eager' })],
});
```
@@ -162,7 +164,7 @@ Plugin scoped services have access to a plugin metadata service, which is a spec
The plugin metadata service is the base for all plugin specific customizations for services. For example, the default implementation of the plugin scoped logger service uses the plugin metadata service to attach the plugin ID as a field in all log messages:
```ts
export const loggerFactory = createServiceFactory({
export const loggerServiceFactory = createServiceFactory({
service: coreServices.logger,
deps: {
rootLogger: coreServices.rootLogger,
@@ -181,7 +183,7 @@ Some services may benefit from having a context that is shared across all instan
The root context is defined as part of the service factory by passing the `createRootContext` option:
```ts
export const fooFactory = createServiceFactory({
export const fooServiceFactory = createServiceFactory({
service: fooServiceRef,
deps: { rootLogger: coreServices.rootLogger, bar: barServiceRef },
createRootContext({ rootLogger }) {
docs/backend-system/architecture/04-plugins.md
+4 -2
View File
@@ -6,6 +6,8 @@ sidebar_label: Plugins
description: Backend plugins
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
Plugins provide the actual base features of a Backstage backend. Each plugin operates completely independently of all other plugins and they only communicate with each other through network calls. This means that there is a strong degree of isolation between plugins, and that each plugin can be considered a separate microservice. While a default Backstage project has all plugins installed within a single backend, it is also possible to split this setup into multiple backends, with each backend housing one or more plugins.
## Defining a Plugin
@@ -20,7 +22,7 @@ import {
} from '@backstage/backend-plugin-api';
export const examplePlugin = createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -51,7 +53,7 @@ export interface ExamplePluginOptions {
export const examplePlugin = createBackendPlugin(
(options?: ExamplePluginOptions) => ({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
docs/backend-system/architecture/05-extension-points.md
+3 -1
View File
@@ -6,6 +6,8 @@ sidebar_label: Extension Points
description: Extension points of backend plugins
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
While plugins are able to accept options for lightweight forms of customization and extension, you quickly hit a limit where you need something more powerful to allow users to extend your plugin. For this purpose, the backend system provides a mechanism for plugins to provide extension points, which can be used to expose deeper customizations for your plugin. Extension points are used by modules, which are installed in the backend adjacent to plugins. Modules are covered more in-depth in the [next section](./06-modules.md).
Extension points are quite similar to services, in that they both encapsulate an interface in a reference object. The key difference is that extension points are registered and provided by plugins themselves, and do not have any factory associated with them. Extension points for a given plugin are also only accessible to modules that extend that same plugin.
@@ -42,7 +44,7 @@ class ActionsExtension implements ScaffolderActionsExtensionPoint {
export const scaffolderPlugin = createBackendPlugin(
{
id: 'scaffolder',
pluginId: 'scaffolder',
register(env) {
const actionsExtensions = new ActionsExtension();
env.registerExtensionPoint(
docs/backend-system/architecture/06-modules.md
+2
View File
@@ -6,6 +6,8 @@ sidebar_label: Modules
description: Modules for backend plugins
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
Backend modules are used to extend [plugins](./04-plugins.md) with additional features or change existing behavior. They must always be installed in the same backend instance as the plugin that they extend, and may only extend a single plugin. Modules interact with their target plugin using the [extension points](./05-extension-points.md) registered by the plugin, while also being able to depend on the [services](./03-services.md) of that plugin.
Both modules and plugins register an `init` method that is called during startup. In order to ensure that modules have registered all their extensions before the plugin starts up, all modules for each plugin are completely initialized before the plugin itself is initialized. In practice this means that all promises returned by each `init` method of the modules need to resolve before the plugin `init` method is called. This also means that it is not possible to further interact with the extension points once the `init` method has resolved.
docs/backend-system/architecture/07-naming-patterns.md
+11 -9
View File
@@ -6,6 +6,8 @@ sidebar_label: Naming Patterns
description: Naming patterns in the backend system
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
These are the naming patterns to adhere to within the backend system. They help us keep exports consistent across packages and make it easier to understand the usage and intent of exports.
### Plugins
@@ -19,7 +21,7 @@ Example:
```ts
export const catalogPlugin = createBackendPlugin({
id: 'catalog',
pluginId: 'catalog',
...
})
```
@@ -34,7 +36,7 @@ export const catalogPlugin = createBackendPlugin({
Example:
```ts
export const catalogModuleGithubEntityProvider = createBackendPlugin({
export const catalogModuleGithubEntityProvider = createBackendModule({
pluginId: 'catalog',
moduleId: 'githubEntityProvider',
...
@@ -64,12 +66,12 @@ export const catalogProcessingExtensionPoint = createExtensionPoint<CatalogProce
### Services
| Description | Pattern | Examples |
| ----------- | ------------------- | -------------------------------------------------- |
| Interface | `<Name>Service` | `LoggerService`, `DatabaseService` |
| Reference | `<name>ServiceRef` | `loggerServiceRef`, `databaseServiceRef` |
| ID | `<pluginId>.<name>` | `'core.rootHttpRouter'`, `'catalog.catalogClient'` |
| Factory | `<name>Factory` | `loggerFactory`, `databaseFactory` |
| Description | Pattern | Examples |
| ----------- | ---------------------- | -------------------------------------------------- |
| Interface | `<Name>Service` | `LoggerService`, `DatabaseService` |
| Reference | `<name>ServiceRef` | `loggerServiceRef`, `databaseServiceRef` |
| ID | `<pluginId>.<name>` | `'core.rootHttpRouter'`, `'catalog.catalogClient'` |
| Factory | `<name>ServiceFactory` | `loggerServiceFactory`, `databaseServiceFactory` |
Example:
@@ -83,7 +85,7 @@ export const catalogClientServiceRef = createServiceRef<CatalogClientService>({
...
})
export const catalogClientFactory = createServiceFactory({
export const catalogClientServiceFactory = createServiceFactory({
service: catalogClientServiceRef,
...
})
docs/backend-system/building-backends/01-index.md
+6 -4
View File
@@ -6,6 +6,8 @@ sidebar_label: Overview
description: Building backends using the new backend system
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
> NOTE: If you have an existing backend that is not yet using the new backend
> system, see [migrating](./08-migrating.md).
@@ -59,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 { configFactory } from '@backstage/backend-app-api';
import { configServiceFactory } from '@backstage/backend-app-api';
const backend = createBackend({
services: [
configFactory({
configServiceFactory({
remote: { reloadIntervalSeconds: 60 },
}),
],
@@ -158,11 +160,11 @@ A shared environment is defined using `createSharedEnvironment`. In this example
```ts
// packages/backend-env/src/index.ts
import { createSharedEnvironment } from '@backstage/backend-plugin-api';
import { customDiscoveryFactory } from './customDiscoveryFactory';
import { customDiscoveryServiceFactory } from './customDiscoveryServiceFactory';
export const env = createSharedEnvironment({
services: [
customDiscoveryFactory(), // custom DiscoveryService implementation
customDiscoveryServiceFactory(), // custom DiscoveryService implementation
],
});
```
docs/backend-system/building-backends/08-migrating.md
+2
View File
@@ -6,6 +6,8 @@ sidebar_label: Migration Guide
description: How to migrate existing backends to the new backend system
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
## Overview
This section describes how to migrate an existing Backstage backend service
docs/backend-system/building-plugins-and-modules/01-index.md
+5 -3
View File
@@ -6,6 +6,8 @@ sidebar_label: Overview
description: Building backend plugins and modules using the new backend system
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
> NOTE: If you have an existing backend and/or backend plugins that are not yet
> using the new backend system, see [migrating](./08-migrating.md).
@@ -34,7 +36,7 @@ import {
import { createExampleRouter } from './router';
export const examplePlugin = createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -181,7 +183,7 @@ that needs to be different across environments.
import { coreServices } from '@backstage/backend-plugin-api';
export const examplePlugin = createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: { config: coreServices.config },
@@ -214,7 +216,7 @@ export interface ExampleOptions {
export const examplePlugin = createBackendPlugin(
(options?: ExampleOptions) => ({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
docs/backend-system/building-plugins-and-modules/02-testing.md
+2
View File
@@ -6,6 +6,8 @@ sidebar_label: Testing
description: Learn how to test your backend plugins and modules
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
Utilities for testing backend plugins and modules are available in
`@backstage/backend-test-utils`. This section describes those facilities.
docs/backend-system/building-plugins-and-modules/08-migrating.md
+5 -3
View File
@@ -6,6 +6,8 @@ sidebar_label: Migration Guide
description: How to migrate existing backend plugins to the new backend system
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
Migrating an existing backend plugin to the new backend system is fairly straightforward. The process is similar across the majority of plugins which just return a `Router` that is then wired up in the `index.ts` file of your backend. The primary thing that we need to do is to make sure that the dependencies that are required by the plugin are available, and then registering the router with the HTTP router service.
Let's look at an example of migrating the Kubernetes backend plugin. In the existing (old) system, the kubernetes backend is structured like this:
@@ -44,7 +46,7 @@ import { Router } from 'express';
import { KubernetesBuilder } from './KubernetesBuilder';
export const kubernetesPlugin = createBackendPlugin({
id: 'kubernetes',
pluginId: 'kubernetes',
register(env) {
env.registerInit({
deps: {
@@ -93,7 +95,7 @@ export interface KubernetesOptions {
}
const kubernetesPlugin = createBackendPlugin((options: KubernetesOptions) => ({
id: 'kubernetes',
pluginId: 'kubernetes',
register(env) {
env.registerInit({
deps: {
@@ -180,7 +182,7 @@ class ClusterSupplier implements KubernetesClusterSupplierExtensionPoint {
}
export const kubernetesPlugin = createBackendPlugin({
id: 'kubernetes',
pluginId: 'kubernetes',
register(env) {
const extensionPoint = new ClusterSupplier();
// We register the extension point with the backend, which allows modules to
docs/backend-system/core-services/01-index.md
+36 -35
View File
@@ -6,6 +6,8 @@ sidebar_label: Core Services
description: Core backend service APIs
---
> **DISCLAIMER: The new backend system is under active development and is not considered stable**
The default backend provides several [core services](https://github.com/backstage/backstage/blob/master/packages/backend-plugin-api/src/services/definitions/coreServices.ts) out of the box which includes access to configuration, logging, URL Readers, databases and more.
All core services are available through the `coreServices` namespace in the `@backstage/backend-plugin-api` package.
@@ -31,7 +33,7 @@ import {
import { Router } from 'express';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: { http: coreServices.httpRouter },
@@ -57,11 +59,11 @@ There's additional configuration that you can optionally pass to setup the `http
You can configure these additional options by adding an override for the core service when calling `createBackend` like follows:
```ts
import { httpRouterFactory } from '@backstage/backend-app-api';
import { httpRouterServiceFactory } from '@backstage/backend-app-api';
const backend = createBackend({
services: [
httpRouterFactory({
httpRouterServiceFactory({
getPath: (pluginId: string) => `/plugins/${pluginId}`,
}),
],
@@ -84,7 +86,7 @@ import {
import { Router } from 'express';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -114,11 +116,11 @@ There's additional options that you can pass to configure the root HTTP Router s
You can configure the root HTTP Router service by passing the options to the `createBackend` function.
```ts
import { rootHttpRouterFactory } from '@backstage/backend-app-api';
import { rootHttpRouterServiceFactory } from '@backstage/backend-app-api';
const backend = createBackend({
services: [
rootHttpRouterFactory({
rootHttpRouterServiceFactory({
configure: ({ app, middleware, routes, config, logger, lifecycle }) => {
// the built in middleware is provided through an option in the configure function
app.use(middleware.helmet());
@@ -155,7 +157,7 @@ import {
} from '@backstage/backend-plugin-api';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -181,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 { configFactory } from '@backstage/backend-app-api';
import { configServiceFactory } from '@backstage/backend-app-api';
const backend = createBackend({
services: [
configFactory({
configServiceFactory({
argv: [
'--config',
'/backstage/app-config.development.yaml',
@@ -213,7 +215,7 @@ import {
} from '@backstage/backend-plugin-api';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -286,7 +288,7 @@ import {
} from '@backstage/backend-plugin-api';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -325,7 +327,7 @@ import {
import { resolvePackagePath } from '@backstage/backend-common';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -364,7 +366,7 @@ import {
import { fetch } from 'node-fetch';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -395,7 +397,7 @@ import {
import { Router } from 'express';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -436,11 +438,11 @@ There's additional configuration that you can optionally pass to setup the `iden
You can configure these additional options by adding an override for the core service when calling `createBackend` like follows:
```ts
import { identityFactory } from '@backstage/backend-app-api';
import { identityServiceFactory } from '@backstage/backend-app-api';
const backend = createBackend({
services: [
identityFactory({
identityServiceFactory({
issuer: 'backstage',
algorithms: ['ES256', 'RS256'],
}),
@@ -463,7 +465,7 @@ import {
} from '@backstage/backend-plugin-api';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -477,10 +479,7 @@ createBackendPlugin({
// do some other stuff.
}, 1000);
lifecycle.addShutdownHook({
fn: () => clearInterval(interval),
logger,
});
lifecycle.addShutdownHook(() => clearInterval(interval));
},
});
},
@@ -497,17 +496,19 @@ The following example shows how to override the default implementation of the li
```ts
class MyCustomLifecycleService implements RootLifecycleService {
constructor(private readonly logger: LoggerService) {
['SIGKILL', 'SIGTERM'].map(signal =>
process.on(signal, () => this.shutdown()),
);
}
constructor(private readonly logger: LoggerService) {}
#isCalled = false;
#shutdownTasks: Array<LifecycleServiceShutdownHook> = [];
#shutdownTasks: Array<{
hook: LifecycleServiceShutdownHook;
options?: LifecycleServiceShutdownOptions;
}> = [];
addShutdownHook(options: LifecycleServiceShutdownHook): void {
this.#shutdownTasks.push(options);
addShutdownHook(
hook: LifecycleServiceShutdownHook,
options?: LifecycleServiceShutdownOptions,
): void {
this.#shutdownTasks.push({ hook, options });
}
async shutdown(): Promise<void> {
@@ -518,10 +519,10 @@ class MyCustomLifecycleService implements RootLifecycleService {
this.logger.info(`Running ${this.#shutdownTasks.length} shutdown tasks...`);
await Promise.all(
this.#shutdownTasks.map(async hook => {
const { logger = this.logger } = hook;
this.#shutdownTasks.map(async ({ hook, options }) => {
const logger = options?.logger ?? this.logger;
try {
await hook.fn();
await hook();
logger.info(`Shutdown hook succeeded`);
} catch (error) {
logger.error(`Shutdown hook failed, ${error}`);
@@ -562,7 +563,7 @@ import {
import { Router } from 'express';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -611,7 +612,7 @@ import {
import { fetch } from 'node-fetch';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
@@ -650,7 +651,7 @@ import {
import os from 'os';
createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env) {
env.registerInit({
deps: {
docs/features/kubernetes/proxy.md
+87
View File
@@ -0,0 +1,87 @@
---
id: proxy
title: Kubernetes Backend Proxy Endpoint
sidebar_label: Proxy
description: Interacting with the Kubernetes API in Backstage plugins
---
[Contributors](https://backstage.io/docs/overview/glossary#backstage-user-profiles) wanting to
create developer portal experiences based on data from Kubernetes (e.g. for
interacting with [Custom
Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
beyond the default behaviors of the existing Kubernetes plugin) can leverage the
Kubernetes backend plugin's proxy endpoint to allow them to make arbitrary
requests to the [REST
API](https://kubernetes.io/docs/reference/using-api/api-concepts/).
Here is a snippet fetching namespaces from a cluster configured with the
`google` [auth provider](https://backstage.io/docs/features/kubernetes/configuration#clustersauthprovider):
```typescript
import {
discoveryApiRef,
googleAuthApiRef,
useApi,
} from '@backstage/core-plugin-api';
const CLUSTER_NAME = ''; // use a known cluster name
// get a bearer token from Google
const googleAuthApi = useApi(googleAuthApiRef);
const token = await googleAuthApi.getAccessToken(
'https://www.googleapis.com/auth/cloud-platform',
);
const discoveryApi = useApi(discoveryApiRef);
const kubernetesBaseUrl = await discoveryApi.getBaseUrl('kubernetes');
const kubernetesProxyEndpoint = `${kubernetesBaseUrl}/proxy`;
// fetch namespaces
await fetch(`${kubernetesProxyEndpoint}/api/v1/namespaces`, {
method: 'GET',
headers: {
'X-Kubernetes-Cluster': CLUSTER_NAME,
Authorization: `Bearer ${token}`,
},
});
```
## How it works
The proxy will interpret the
[`X-Kubernetes-Cluster`
header](https://backstage.io/docs/reference/plugin-kubernetes-backend.header_kubernetes_cluster)
as the name of the cluster to target. This name will be compared to each cluster
returned by all the configured [cluster
locators](https://backstage.io/docs/features/kubernetes/configuration#clusterlocatormethods)
-- the first cluster whose [`name` field](https://backstage.io/docs/features/kubernetes/configuration#clustersname) matches
the value in the header will be targeted.
Then the request will be forwarded verbatim (but with the endpoint's base URL
prefix stripped) to the cluster.
## Authentication
Until some security and permission decisions are made (see [this
conversation](https://github.com/backstage/backstage/pull/13026/files#r1029376939)
for context), contributors consuming the proxy endpoint in their plugin code are
responsible for negotiating their own bearer token out-of-band. This requires
knowing some auth details about the cluster being contacted -- in practice, only
clusters with [client side auth
providers](https://backstage.io/docs/features/kubernetes/authentication#client-side-providers) can reasonably be reached.
The proxy has no provisions for mTLS, so it cannot be used to connect to
clusters using the [x509 Client
Certs](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#x509-client-certs)
authentication strategy. [Bearer
tokens](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#putting-a-bearer-token-in-a-request)
will be forwarded as-is.
## Other known limitations
The proxy as it was released in [Backstage
1.9](https://github.com/backstage/backstage/blob/master/docs/releases/v1.9.0-changelog.md#patch-changes-15)
has a known bug:
- [#15901](https://github.com/backstage/backstage/issues/15901) - it cannot
reliably target clusters who share the same name with another located cluster.
docs/features/search/how-to-guides.md
+14
View File
@@ -235,6 +235,20 @@ export const YourSearchResultListItemExtension = plugin.provide(
);
```
If your list item accept props, you can extend the `SearchResultListItemExtensionProps` with your component specific props:
```tsx
export const YourSearchResultListItemExtension: (
props: SearchResultListItemExtensionProps<YourSearchResultListItemProps>,
) => JSX.Element | null = plugin.provide(
createSearchResultListItemExtension({
name: 'YourSearchResultListItem',
component: () =>
import('./components').then(m => m.YourSearchResultListItem),
}),
);
```
Additionally, you can define a predicate function that receives a result and returns whether your extension should be used to render it or not:
```tsx
docs/features/software-catalog/external-integrations.md
+6 -6
View File
@@ -89,23 +89,23 @@ export class FrobsProvider implements EntityProvider {
private readonly reader: UrlReader;
private connection?: EntityProviderConnection;
/** [1] **/
/** [1] */
constructor(env: string, reader: UrlReader) {
this.env = env;
this.reader = reader;
}
/** [2] **/
/** [2] */
getProviderName(): string {
return `frobs-${this.env}`;
}
/** [3] **/
/** [3] */
async connect(connection: EntityProviderConnection): Promise<void> {
this.connection = connection;
}
/** [4] **/
/** [4] */
async run(): Promise<void> {
if (!this.connection) {
throw new Error('Not initialized');
@@ -116,10 +116,10 @@ export class FrobsProvider implements EntityProvider {
);
const data = JSON.parse(await response.buffer()).toString();
/** [5] **/
/** [5] */
const entities: Entity[] = frobsToEntities(data);
/** [6] **/
/** [6] */
await this.connection.applyMutation({
type: 'full',
entities: entities.map(entity => ({
docs/features/software-catalog/system-model.md
+27
View File
@@ -63,6 +63,17 @@ BigTable databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together
with components and systems will better allow us to visualize resource
footprint, and create tooling around them.
##Organizational Entities
### User
A user describes a person, such as an employee, a contractor, or similar.
### Group
A group describes an organizational entity, such as for example a team, a
business unit, or a loose collection of people in an interest group.
## Ecosystem Modeling
A large catalogue of components, APIs and resources can be highly granular and
@@ -108,3 +119,19 @@ domain would come with some documentation on how to accept payments for a new
product or use-case, share the same entity types in their APIs, and integrate
well with each other. Other domains could be “Content Ingestion”, “Ads” or
“Search”.
##Other
### Location
A location is a marker that references other places to look for catalog data.
### Type
The type field in the system has no set meaning. It is up to the user to assign their own types and use them as desired, such as for link validation or creating custom UI components. Some common pre-defined types are depicted in the ecosystem modeling diagram.
### Template
A template definition describes both the parameters that are rendered in the
frontend part of the scaffolding wizard, and the steps that are executed when
scaffolding that component.
docs/features/software-templates/writing-custom-actions.md
+1
View File
@@ -168,5 +168,6 @@ scaffolder backend:
| Scaffolder Git Actions | [plugin-scaffolder-git-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-git-actions) | [Drew Hill](https://github.com/arhill05) |
| Azure Pipeline Actions | [scaffolder-backend-module-azure-pipelines](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-pipelines) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) |
| Azure Repository Actions | [scaffolder-backend-module-azure-repositories](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-repositories) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) |
| Snyk Import Project | [plugin-scaffolder-backend-module-snyk](https://www.npmjs.com/package/@ma11hewthomas/plugin-scaffolder-backend-module-snyk) | [Matthew Thomas](https://github.com/Ma11hewThomas) |
Have fun! 🚀
docs/features/software-templates/writing-templates.md
+5 -5
View File
@@ -112,11 +112,11 @@ steps which would be rendered as different steps in the scaffolder plugin
frontend.
Each `Step` is `JSONSchema` with some extra goodies for styling what it might
look like in the frontend. For these steps we rely very heavily on this library:
https://github.com/rjsf-team/react-jsonschema-form. They have some great docs
too here: https://react-jsonschema-form.readthedocs.io/ and a playground where
you can play around with some examples here
https://rjsf-team.github.io/react-jsonschema-form.
look like in the frontend. For these steps we rely very heavily on this
[library](https://github.com/rjsf-team/react-jsonschema-form). They have some
[great docs](https://rjsf-team.github.io/react-jsonschema-form/docs/) and a
[playground](https://rjsf-team.github.io/react-jsonschema-form) where you can
play around with some examples.
There's another option for that library called `uiSchema` which we've taken
advantage of, and we've merged it with the existing `JSONSchema` that you
docs/features/techdocs/addons.md
+1
View File
@@ -125,6 +125,7 @@ discover available Addons, we've compiled a list of them here:
| [`<ExpandableNavigation />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. |
| [`<ReportIssue />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. |
| [`<TextSize />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. |
| [`<LightBox />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. |
Got an Addon to contribute? Feel free to add a row above!
docs/features/techdocs/getting-started.md
+2 -2
View File
@@ -262,12 +262,12 @@ You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g.
apt).
You can do so by including the following lines in the last step of your
You can do so by including the following lines right above `USER node` of your
`Dockerfile`:
```Dockerfile
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install mkdocs-techdocs-core==1.0.1
RUN pip3 install mkdocs-techdocs-core==1.1.7
```
Please be aware that the version requirement could change, you need to check our
docs/integrations/azure/locations.md
+2
View File
@@ -28,3 +28,5 @@ The configuration is a structure with two elements:
- `host`: The DevOps host; only `dev.azure.com` is supported.
- `token` (optional): A personal access token as expected by Azure DevOps.
> Note: The token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
docs/integrations/gitlab/discovery.md
+2 -2
View File
@@ -22,9 +22,9 @@ catalog:
yourProviderId:
host: gitlab-host # Identifies one of the hosts set up in the integrations
branch: main # Optional. Uses `master` as default
group: example-group # Optional. Group and subgroup (if needed) to look for repositories. If not present the whole project will be scanned
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]*/`, what means to not filter anything
projectPattern: '[\s\S]*' # Optional. Filters found projects based on provided patter. Defaults to `[\s\S]*`, which means to not filter anything
schedule: # optional; same options as in TaskScheduleDefinition
# supports cron, ISO duration, "human duration" as used in code
frequency: { minutes: 30 }
docs/permissions/overview.md
+2
View File
@@ -34,6 +34,8 @@ The permission framework was designed with a few key properties in mind:
4. An authorization decision is sent to the plugin from the permission backend.
5. The user is either granted access or an error is shown. The plugin is responsible for implementing a response to the user.
## How do I get started?
See the "[getting started](./getting-started.md)" permission documentation for Backstage integrators.
docs/permissions/plugin-authors/01-setup.md
+6 -3
View File
@@ -26,6 +26,9 @@ The source code is available here:
git checkout master -- plugins/example-todo-list/
git checkout master -- plugins/example-todo-list-backend/
git checkout master -- plugins/example-todo-list-common/
sed -i '' 's/workspace:\^/\*/g' plugins/example-todo-list/package.json
sed -i '' 's/workspace:\^/\*/g' plugins/example-todo-list-backend/package.json
sed -i '' 's/workspace:\^/\*/g' plugins/example-todo-list-common/package.json
for file in plugins/*; do mv "$file" "$OLDPWD/${file/example-todo/todo}"; done
cd -
```
@@ -37,15 +40,15 @@ The source code is available here:
2. Add these packages as dependencies for your Backstage app:
```
$ yarn workspace backend add @internal/plugin-todo-list-backend@^1.0.0 @internal/plugin-todo-list-common@^1.0.0
$ yarn workspace app add @internal/plugin-todo-list@^1.0.0
$ yarn workspace backend add @internal/plugin-todo-list-backend @internal/plugin-todo-list-common
$ yarn workspace app add @internal/plugin-todo-list
```
3. Include the backend and frontend plugin in your application:
Create a new `packages/backend/src/plugins/todolist.ts` with the following content:
```javascript
```typescript
import { DefaultIdentityClient } from '@backstage/plugin-auth-node';
import { createRouter } from '@internal/plugin-todo-list-backend';
import { Router } from 'express';
docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md
+43 -3
View File
@@ -146,7 +146,7 @@ In order to test the logic above, the integrators of your backstage instance nee
- async handle(): Promise<PolicyDecision> {
+ async handle(
+ request: PolicyQuery,
+ user?: BackstageIdentityResponse,
+ _user?: BackstageIdentityResponse,
+ ): Promise<PolicyDecision> {
+ if (isPermission(request.permission, todoListCreatePermission)) {
+ return {
@@ -204,7 +204,7 @@ First we'll clean up the `plugins/todo-list-backend/src/service/router.test.ts`:
const router = await createRouter({
logger: getVoidLogger(),
identity: {} as DefaultIdentityClient,
+ permissions: toPermissionEvaluator,
+ permissions: permissionEvaluator,
});
app = express().use(router);
});
@@ -235,7 +235,7 @@ Then we want to update the `plugins/todo-list-backend/src/service/standaloneServ
+ ServerTokenManager,
} from '@backstage/backend-common';
import { DefaultIdentityClient } from '@backstage/plugin-auth-node';
import { ServerPermissionClient } from '@backstage/plugin-permission-node';
+ import { ServerPermissionClient } from '@backstage/plugin-permission-node';
import { Server } from 'http';
import { Logger } from 'winston';
import { createRouter } from './router';
@@ -285,4 +285,44 @@ Then we want to update the `plugins/todo-list-backend/src/service/standaloneServ
module.hot?.accept();
```
Finally, we need to update `plugins/todo-list-backend/src/plugin.ts`:
```diff
import { loggerToWinstonLogger } from '@backstage/backend-common';
import {
coreServices,
createBackendPlugin,
} from '@backstage/backend-plugin-api';
import { createRouter } from './service/router';
/**
* The example TODO list backend plugin.
*
* @alpha
*/
export const exampleTodoListPlugin = createBackendPlugin({
pluginId: 'exampleTodoList',
register(env) {
env.registerInit({
deps: {
identity: coreServices.identity,
logger: coreServices.logger,
httpRouter: coreServices.httpRouter,
+ permissions: coreServices.permissions,
},
- async init({ identity, logger, httpRouter }) {
+ async init({ identity, logger, httpRouter, permissions }) {
httpRouter.use(
await createRouter({
identity,
logger: loggerToWinstonLogger(logger),
permissions,
}),
);
},
});
},
});
```
Now when you run `yarn tsc` you should have no more errors.
docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md
+12 -6
View File
@@ -76,7 +76,7 @@ This enables decisions based on characteristics of the resource, but it's import
Install the missing module:
```
$ yarn workspace @internal/plugin-todo-list-backend add @backstage/plugin-permission-node
$ yarn workspace @internal/plugin-todo-list-backend add @backstage/plugin-permission-node zod
```
Create a new `plugins/todo-list-backend/src/service/rules.ts` file and append the following code:
@@ -89,7 +89,8 @@ import { Todo, TodoFilter } from './todos';
export const createTodoListPermissionRule = makeCreatePermissionRule<
Todo,
TodoFilter
TodoFilter,
typeof TODO_LIST_RESOURCE_TYPE
>();
export const isOwner = createTodoListPermissionRule({
@@ -97,8 +98,8 @@ export const isOwner = createTodoListPermissionRule({
description: 'Should allow only if the todo belongs to the user',
resourceType: TODO_LIST_RESOURCE_TYPE,
paramsSchema: z.object({
userId: z.string().describe('User ID to match on the resource')
})
userId: z.string().describe('User ID to match on the resource'),
}),
apply: (resource: Todo, { userId }) => {
return resource.author === userId;
},
@@ -187,6 +188,7 @@ Make sure `todoListConditions` and `createTodoListConditionalDecision` are expor
```diff
export * from './service/router';
+ export * from './conditionExports';
export { exampleTodoListPlugin } from './plugin';
```
## Test the authorized update endpoint
@@ -209,7 +211,6 @@ Let's go back to the permission policy's handle function and try to authorize ou
+ import {
+ todoListCreatePermission,
+ todoListUpdatePermission,
+ TODO_LIST_RESOURCE_TYPE,
+ } from '@internal/plugin-todo-list-common';
+ import {
+ todoListConditions,
@@ -217,7 +218,11 @@ Let's go back to the permission policy's handle function and try to authorize ou
+ } from '@internal/plugin-todo-list-backend';
...
async handle(
request: PolicyQuery,
- _user?: BackstageIdentityResponse,
+ user?: BackstageIdentityResponse,
): Promise<PolicyDecision> {
if (isPermission(request.permission, todoListCreatePermission)) {
return {
result: AuthorizeResult.ALLOW,
@@ -236,6 +241,7 @@ Let's go back to the permission policy's handle function and try to authorize ou
return {
result: AuthorizeResult.ALLOW,
};
}
```
For any incoming update requests, we now return a _Conditional Decision_. We are saying:
docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md
+5 -8
View File
@@ -15,7 +15,7 @@ One possible solution may leverage the batching functionality to authorize all o
- res.json(getAll())
+ const items = getAll();
+ const decisions = await permissions.authorize(
+ items.map(({ id }) => ({ permission: todosListRead, resourceRef: id })),
+ items.map(({ id }) => ({ permission: todoListReadPermission, resourceRef: id })),
+ );
+ const filteredItems = decisions.filter(
@@ -53,7 +53,7 @@ Let's add another permission to the plugin.
resourceType: TODO_LIST_RESOURCE_TYPE,
});
+
+ export const todosListRead = createPermission({
+ export const todoListReadPermission = createPermission({
+ name: 'todos.list.read',
+ attributes: { action: 'read' },
+ resourceType: TODO_LIST_RESOURCE_TYPE,
@@ -81,10 +81,9 @@ So far we've only used the `PermissionEvaluator.authorize` method, which will ev
import {
todosListCreate,
todosListUpdate,
+ todosListRead,
+ todoListReadPermission,
TODO_LIST_RESOURCE_TYPE,
} from './permissions';
+ import { rules } from './rules';
+ const transformConditions: ConditionTransformer<TodoFilter> = createConditionTransformer(Object.values(rules));
@@ -95,7 +94,7 @@ So far we've only used the `PermissionEvaluator.authorize` method, which will ev
+ );
+
+ const decision = (
+ await permissions.authorizeConditional([{ permission: todosListRead }], {
+ await permissions.authorizeConditional([{ permission: todoListReadPermission }], {
+ token,
+ })
+ )[0];
@@ -110,7 +109,6 @@ So far we've only used the `PermissionEvaluator.authorize` method, which will ev
+ } else {
+ res.json(getAll());
+ }
+ }
- res.json(getAll());
});
```
@@ -121,7 +119,7 @@ Since `TodoFilter` used in our plugin matches the structure of the conditions ob
## Test the authorized read endpoint
Let's update our permission policy to return a conditional result whenever a `todosListRead` permission is received. In this case, we can reuse the decision returned for the `todosListCreate` permission.
Let's update our permission policy to return a conditional result whenever a `todoListReadPermission` permission is received. In this case, we can reuse the decision returned for the `todosListCreate` permission.
```diff
// packages/backend/src/plugins/permission.ts
@@ -132,7 +130,6 @@ import {
todoListCreatePermission,
todoListUpdatePermission,
+ todoListReadPermission,
TODO_LIST_RESOURCE_TYPE,
} from '@internal/plugin-todo-list-common';
...
docs/permissions/plugin-authors/05-frontend-authorization.md
+15 -4
View File
@@ -56,7 +56,11 @@ Let's make the following changes in `plugins/todo-list/src/components/TodoListPa
- Add
- </Button>
+ {!loadingPermission && (
+ <Button disabled={!canAddTodo} variant="contained" onClick={handleAdd}>
+ <Button
+ disabled={!canAddTodo}
+ variant="contained"
+ onClick={() => onAdd(title.current)}
+ >
+ Add
+ </Button>
+ )}
@@ -118,7 +122,10 @@ Providing a disabled state can be a helpful signal to users, but there may be ca
- <Grid item>
- <AddTodo onAdd={handleAdd} />
- </Grid>
+ <RequirePermission permission={todoListCreatePermission} errorPage={<></>}>
+ <RequirePermission
+ permission={todoListCreatePermission}
+ errorPage={<></>}
+ >
+ <Grid item>
+ <AddTodo onAdd={handleAdd} />
+ </Grid>
@@ -149,11 +156,15 @@ Providing a disabled state can be a helpful signal to users, but there may be ca
onChange={e => (title.current = e.target.value)}
/>
- {!loadingPermission && (
- <Button disabled={!canAddTodo} variant="contained" onClick={handleAdd}>
- <Button
- disabled={!canAddTodo}
- variant="contained"
- onClick={() => onAdd(title.current)}
- >
- Add
- </Button>
- )}
+ <Button variant="contained" onClick={handleAdd}>
+ <Button variant="contained" onClick={() => onAdd(title.current)}>
+ Add
+ </Button>
</Box>
docs/plugins/new-backend-system.md
+2 -2
View File
@@ -84,7 +84,7 @@ import {
// export type ExamplePluginOptions = { exampleOption: boolean };
export const examplePlugin = createBackendPlugin({
// unique id for the plugin
id: 'example',
pluginId: 'example',
// It's possible to provide options to the plugin
// register(env, options: ExamplePluginOptions) {
register(env) {
@@ -111,7 +111,7 @@ If we wanted our plugin to accept options as well, we'd accept the options as th
```ts
export const examplePlugin = createBackendPlugin({
id: 'example',
pluginId: 'example',
register(env, options?: { silent?: boolean }) {
env.registerInit({
deps: { logger: coreServices.logger },
docs/plugins/url-reader.md
+1 -1
View File
@@ -40,7 +40,7 @@ i.e.`packages/backend/src/index.ts`.
```ts
// File: packages/backend/src/index.ts
import { URLReaders } from '@backstage/backend-common';
import { UrlReaders } from '@backstage/backend-common';
function makeCreateEnv(config: Config) {
// ....
docs/releases/v1.11.0-next.1-changelog.md
+2164
View File
File diff suppressed because it is too large Load Diff
docs/releases/v1.11.0-next.2-changelog.md
+2289
View File
File diff suppressed because it is too large Load Diff