Merge remote-tracking branch 'upstream/master' into entra-rename
This commit is contained in:
Alex Crome
@@ -406,3 +406,50 @@ providerFactories: {
|
||||
ghe: providers.github.create(),
|
||||
},
|
||||
```
|
||||
|
||||
## Configuring token issuers
|
||||
|
||||
By default, the Backstage authentication backend generates and manages its own signing keys automatically for any issued
|
||||
Backstage tokens. However, these keys have a short lifetime and do not persist after instance restarts.
|
||||
|
||||
Alternatively, users can provide their own public and private key files to sign issued tokens. This is beneficial in
|
||||
scenarios where the token verification implementation aggressively caches the list of keys, and doesn't attempt to fetch
|
||||
new ones even if they encounter an unknown key id. To enable this feature add the following configuration to your config
|
||||
file:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
keyStore:
|
||||
provider: 'static'
|
||||
static:
|
||||
keys:
|
||||
# Must be declared at least once and the first one will be used for signing
|
||||
- keyId: 'primary'
|
||||
publicKeyFile: /path/to/public.key
|
||||
privateKeyFile: /path/to/private.key
|
||||
algorithm: # Optional, algorithm used to generate the keys, defaults to ES256
|
||||
# More keys can be added so with future key rotations caches already know about it
|
||||
- keyId: ...
|
||||
```
|
||||
|
||||
The private key should be stored in the PKCS#8 format. The public key should be stored in the SPKI format.
|
||||
You can generate the public/private key pair, using openssl and the ES256 algorithm by performing the following
|
||||
steps:
|
||||
|
||||
Generate a private key using the ES256 algorithm
|
||||
|
||||
```sh
|
||||
openssl ecparam -name prime256v1 -genkey -out private.ec.key
|
||||
```
|
||||
|
||||
Convert it to PKCS#8 format
|
||||
|
||||
```sh
|
||||
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.ec.key -out private.key
|
||||
```
|
||||
|
||||
Extract the public key
|
||||
|
||||
```sh
|
||||
openssl ec -inform PEM -outform PEM -pubout -in private.key -out public.key
|
||||
```
|
||||
|
||||
@@ -38,13 +38,18 @@ auth:
|
||||
clientId: ${AUTH_MICROSOFT_CLIENT_ID}
|
||||
clientSecret: ${AUTH_MICROSOFT_CLIENT_SECRET}
|
||||
tenantId: ${AUTH_MICROSOFT_TENANT_ID}
|
||||
domainHint: ${AZURE_TENANT_ID}
|
||||
```
|
||||
|
||||
The Microsoft provider is a structure with three configuration keys:
|
||||
The Microsoft provider is a structure with three mandatory configuration keys:
|
||||
|
||||
- `clientId`: Application (client) ID, found on App Registration > Overview
|
||||
- `clientSecret`: Secret, found on App Registration > Certificates & secrets
|
||||
- `tenantId`: Directory (tenant) ID, found on App Registration > Overview
|
||||
- `domainHint` (optional): Typically the same as `tenantId`.
|
||||
Leave blank if your app registration is multi tenant.
|
||||
When specified, this reduces login friction for users with accounts in multiple tenants by automatically filtering away accounts from other tenants.
|
||||
For more details, see [Home Realm Discovery](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy)
|
||||
|
||||
## Outbound Network Access
|
||||
|
||||
|
||||
@@ -10,6 +10,6 @@ description: The Backend System
|
||||
|
||||
## Status
|
||||
|
||||
The new backend system is in alpha, and only a small number of plugins have been migrated so far. It is possible to try it out, but it is not recommended to use this new system in production yet.
|
||||
The new backend system is in alpha, but many plugins have already been migrated. We recommend all plugins to migrate to the new system, and you can also try it out in your own production deployments.
|
||||
|
||||
You can find an example backend setup in [the `backend-next` package](https://github.com/backstage/backstage/tree/master/packages/backend-next).
|
||||
|
||||
@@ -107,7 +107,9 @@ $ 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/).
|
||||
Second, install the [Pulumi CLI](https://www.pulumi.com/docs/get-started/install/) - `backstage-deploy` uses it to
|
||||
simplify the management of cloud resources (Pulumi allows us to simply specify the desired "target cloud state", and
|
||||
Pulumi will intelligently create/modify/delete resources to reach that state. Nice!).
|
||||
|
||||
Then we need to execute the following commands, to set Pulumi up:
|
||||
|
||||
@@ -126,9 +128,9 @@ By using `pulumi login --local` we are making sure that Pulumi stores our state
|
||||
|
||||
## Deploying your instance on Lightsail
|
||||
|
||||
:::warning
|
||||
:::tip
|
||||
|
||||
Make sure that [Docker](https://docs.docker.com/) is running before you start this section.
|
||||
Make sure that [Docker](https://docs.docker.com/) is running on your machine before you start this section.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@@ -114,18 +114,18 @@ of the `SearchType` component.
|
||||
|
||||
> Check out the documentation around [integrating search into plugins](../../plugins/integrating-search-into-plugins.md#create-a-collator) for how to create your own collator.
|
||||
|
||||
## How to customize fields in the Software Catalog index
|
||||
## How to customize fields in the Software Catalog or TechDocs index
|
||||
|
||||
Sometimes you will might want to have ability to control
|
||||
which data passes to search index in catalog collator, or to customize data for specific kind.
|
||||
You can easily do that by passing `entityTransformer` callback to `DefaultCatalogCollatorFactory`.
|
||||
You can either just simply amend default behaviour, or even to write completely new document
|
||||
(which should follow some required basic structure though).
|
||||
Sometimes, you might want to have the ability to control which data passes into the search index
|
||||
in the catalog collator or customize data for a specific kind. You can easily achieve this
|
||||
by passing an `entityTransformer` callback to the `DefaultCatalogCollatorFactory`. This behavior
|
||||
is also possible for the `DefaultTechDocsCollatorFactory`. You can either simply amend the default behavior
|
||||
or even write an entirely new document (which should still follow some required basic structure).
|
||||
|
||||
> `authorization` and `location` cannot be modified via a `entityTransformer`, `location` can be modified only through `locationTemplate`.
|
||||
|
||||
```ts title="packages/backend/src/plugins/search.ts"
|
||||
const entityTransformer: CatalogCollatorEntityTransformer = (
|
||||
const catalogEntityTransformer: CatalogCollatorEntityTransformer = (
|
||||
entity: Entity,
|
||||
) => {
|
||||
if (entity.kind === 'SomeKind') {
|
||||
@@ -146,7 +146,26 @@ indexBuilder.addCollator({
|
||||
discovery: env.discovery,
|
||||
tokenManager: env.tokenManager,
|
||||
/* highlight-add-next-line */
|
||||
entityTransformer,
|
||||
entityTransformer: catalogEntityTransformer,
|
||||
}),
|
||||
});
|
||||
|
||||
const techDocsEntityTransformer: TechDocsCollatorEntityTransformer = (
|
||||
entity: Entity,
|
||||
) => {
|
||||
return {
|
||||
// add more fields to the index
|
||||
...defaultTechDocsCollatorEntityTransformer(entity),
|
||||
tags: entity.metadata.tags,
|
||||
};
|
||||
};
|
||||
|
||||
indexBuilder.addCollator({
|
||||
collator: DefaultTechDocsCollatorFactory.fromConfig(env.config, {
|
||||
discovery: env.discovery,
|
||||
tokenManager: env.tokenManager,
|
||||
/* highlight-add-next-line */
|
||||
entityTransformer: techDocsEntityTransformer,
|
||||
}),
|
||||
});
|
||||
```
|
||||
|
||||
@@ -674,38 +674,3 @@ To add subpath exports to an existing package, simply add the desired `"exports"
|
||||
```bash
|
||||
yarn backstage-cli migrate package-exports
|
||||
```
|
||||
|
||||
## Experimental Type Build
|
||||
|
||||
> Note: Experimental type builds are deprecated and will be removed in the future. They have been replaced by [subpath exports](#subpath-exports).
|
||||
|
||||
The Backstage CLI has an experimental feature where multiple different type definition files can be generated for different release stages. The release stages are marked in the [TSDoc](https://tsdoc.org/) for each individual export, using either `@public`, `@alpha`, or `@beta`. Rather than just building a single `index.d.ts` file, the build process will instead output `index.d.ts`, `index.beta.d.ts`, and `index.alpha.d.ts`. Each of these files will have exports from more unstable release stages stripped, meaning that `index.d.ts` will omit all exports marked with `@alpha` or `@beta`, while `index.beta.d.ts` will omit all exports marked with `@alpha`.
|
||||
|
||||
This feature is aimed at projects that publish to package registries and wish to maintain different levels of API stability within each package. There is no need to use this within a single monorepo, as it has no effect due to only applying to built and published packages.
|
||||
|
||||
In order for the experimental type build to work, `@microsoft/api-extractor` must be installed in your project, as it is an optional peer dependency of the Backstage CLI. There are then three steps that need to be taken for each package where you want to enable this feature:
|
||||
|
||||
- Add the `--experimental-type-build` flag to the `"build"` script of the package.
|
||||
- Add either one or both of `"alphaTypes"` and `"betaTypes"` to the `"publishConfig"` of the package:
|
||||
```json
|
||||
"publishConfig": {
|
||||
...
|
||||
"types": "dist/index.d.ts",
|
||||
"alphaTypes": "dist/index.alpha.d.ts",
|
||||
"betaTypes": "dist/index.beta.d.ts"
|
||||
},
|
||||
```
|
||||
- Add either one or both of `"alpha"` and `"beta"` to the `"files"` of the package:
|
||||
```json
|
||||
"files": [
|
||||
"dist",
|
||||
"alpha",
|
||||
"beta"
|
||||
]
|
||||
```
|
||||
|
||||
Once this setup is complete, users of the published packages will only be able to access the stable API via the main package entry point, for example `@acme/my-plugin`. Exports marked with `@alpha` or `@beta` will only be available via the `/alpha` entry point, for example `@acme/my-plugin/alpha`, and exports marked with `@beta` will only be available via `/beta`. This does not apply within the monorepo that contains the package. There all exports still have to be imported via the main entry point.
|
||||
|
||||
Note that these different entry points are only separated during type checking. At runtime they all share the same code which contains the exports from all releases stages.
|
||||
|
||||
An example of this setup can be seen in the [`@backstage/catalog-model`](https://github.com/backstage/backstage/blob/da0675bf9f28ed1460f03635a22d3c26abd14707/packages/catalog-model/package.json#L14) package, which has enabled `alpha` type exports. With this setup, exports marked as `@alpha` are only available for import via `@backstage/catalog-model/alpha`. The `@backstage/catalog-model` package currently does not have any exports marked as `@beta`, or a `/beta` entry point.
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
## OpenAPI Validation using Test Cases
|
||||
|
||||
This is primarily performed by `backstage-repo-tools schema openapi test`. Any errors found in the generated specs can be either
|
||||
|
||||
1. Fixed manually, this is usually relevant for request body or response body changes.
|
||||
2. Fixed automatically with `backstage-repo-tools schema openapi test --update`.
|
||||
3. Fixing the test case. This can happen where a response is mocked as
|
||||
|
||||
```ts
|
||||
it('should return the right value', () => {
|
||||
// We will assume that this is the actual response and update the spec accordingly.
|
||||
// Ideally, this should be a fully populated return value.
|
||||
const entity: Entity = {} as any;
|
||||
app.get('/test', () => {
|
||||
return entity;
|
||||
});
|
||||
const response = await request(app).get('/test');
|
||||
expect(response.body).toEqual(entity);
|
||||
});
|
||||
```
|
||||
|
||||
will cause an invalid spec validation. The return value doesn't have all properties as defined in the type. Try to avoid this if possible. Something better would be,
|
||||
|
||||
```ts
|
||||
it('should return the right value', () => {
|
||||
// We will assume that this is the actual response and update the spec accordingly.
|
||||
// Ideally, this should be a fully populated return value.
|
||||
const entity: Entity = {
|
||||
apiVersion: 'a1',
|
||||
kind: 'k1',
|
||||
metadata: { name: 'n1' },
|
||||
};
|
||||
app.get('/test', () => {
|
||||
return entity;
|
||||
});
|
||||
const response = await request(app).get('/test');
|
||||
expect(response.body).toEqual(entity);
|
||||
});
|
||||
```
|
||||
|
||||
Additionally, for more advanced use cases, you can run `yarn optic capture {PATH_TO_OPENAPI_FILE} --update interactive` and go through the prompts on the screen. Under the hood, the test validation + updating is done by [Optic](https://github.com/opticdev/optic), a great project around supporting OpenAPI specs and development. You can find additional options [here](https://www.useoptic.com/docs/verify-openapi).
|
||||
@@ -349,7 +349,7 @@ import { createRouter } from './service/router';
|
||||
/**
|
||||
* The example TODO list backend plugin.
|
||||
*
|
||||
* @alpha
|
||||
* @public
|
||||
*/
|
||||
export const exampleTodoListPlugin = createBackendPlugin({
|
||||
pluginId: 'exampleTodoList',
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -4,8 +4,6 @@ title: Migration to Yarn 3
|
||||
description: Guide for how to migrate a Backstage project to use Yarn 3
|
||||
---
|
||||
|
||||
> NOTE: We do not yet recommend all projects to migrate to Yarn 3. Only do so if you have specific reasons for it.
|
||||
|
||||
While Backstage projects created with `@backstage/create-app` use [Yarn 1](https://classic.yarnpkg.com/) by default, it
|
||||
is possible to switch them to instead use [Yarn 3](https://yarnpkg.com/). Tools like `yarn backstage-cli versions:bump` will
|
||||
still work, as they recognize both lockfile formats.
|
||||
|
||||
Reference in New Issue
Block a user