Merge branch 'master' into scaffolder-each
This commit is contained in:
Alex Eftimie
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user