Merge remote-tracking branch 'origin/master' into package-workspaces
This commit is contained in:
Gabriel Dugny
@@ -156,7 +156,6 @@ These colors form a layered neutral scale for your application backgrounds. `--b
|
||||
| Token Name | Description |
|
||||
| ----------------------------- | ------------------------------------------------------------ |
|
||||
| `--bui-bg-app` | The base background color of your Backstage instance. |
|
||||
| `--bui-bg-popover` | The background color used for popovers, tooltips, and menus. |
|
||||
| `--bui-bg-neutral-1` | First elevated layer. Use for cards, dialogs, and panels. |
|
||||
| `--bui-bg-neutral-1-hover` | Hover state for elements on neutral-1. |
|
||||
| `--bui-bg-neutral-1-pressed` | Pressed state for elements on neutral-1. |
|
||||
|
||||
@@ -210,6 +210,191 @@ if `prevCursor` exists, it can be used to retrieve the previous batch of entitie
|
||||
it isn't possible to change any of [`filter`, `orderField`, `fullTextFilter`] when passing `cursor` as query parameters,
|
||||
as changing any of these properties will affect pagination. If any of `filter`, `orderField`, `fullTextFilter` is specified together with `cursor`, only the latter is taken into consideration.
|
||||
|
||||
### `POST /entities/by-query`
|
||||
|
||||
This supports the same features as the `GET` variant, but in a `POST` body to
|
||||
not have to abide by URL length limits. Additionally, it supports advanced, more
|
||||
expressive querying format - see below. The response format is identical.
|
||||
|
||||
#### Querying by filter predicate
|
||||
|
||||
You can pass in a filter predicate to select a subset of entities in the
|
||||
catalog. They are comprised of an optional logical expression tree (using
|
||||
`$all`, `$any`, `$not`), ending in filter sets that can have custom matchers
|
||||
(e.g. `$exists`, `$in`, `$hasPrefix`, `$contains`).
|
||||
|
||||
This is an example of what such a filter predicate expression might look like:
|
||||
|
||||
```js
|
||||
{
|
||||
"query": {
|
||||
"$all": [
|
||||
{
|
||||
"kind": "Component",
|
||||
"spec.type": { "$in": ["service", "website"] }
|
||||
},
|
||||
{
|
||||
"$not": {
|
||||
"metadata.annotations.backstage.io/orphan": "true"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A filter set is an object whose keys are dot separated paths into an object, and
|
||||
the values are either primitives (string, number, or boolean) or custom matchers
|
||||
as per below. An example of a simple such filter set is:
|
||||
|
||||
```js
|
||||
// All of the following must be true for a given entity (there's an
|
||||
// implicit AND between them)
|
||||
{
|
||||
// The kind field is matched against a literal, case insensitively
|
||||
"kind": "Component",
|
||||
// The type field inside the spec is matched using a custom matcher, see below
|
||||
"spec.type": { "$in": ["service", "website"] }
|
||||
}
|
||||
```
|
||||
|
||||
The root of the query is always an object, whether there is a logic expression
|
||||
tree or not. Nodes with a single key that starts with a `$` sign have special
|
||||
meaning.
|
||||
|
||||
- `$not`: Logical negation.
|
||||
|
||||
Its value must be a single expression. Example:
|
||||
|
||||
```js
|
||||
// Matches entities that do NOT have kind Component
|
||||
{
|
||||
"$not": {
|
||||
"kind": "Component",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note that `$not` cannot be used in a right hand side value matcher.
|
||||
|
||||
```js
|
||||
// ❌ WRONG
|
||||
{ "kind": { "$not": "Component" } }
|
||||
// ✅ CORRECT
|
||||
{ "$not": { "kind": "Component" } }
|
||||
```
|
||||
|
||||
- `$all`: Require that all given expressions match each entity.
|
||||
|
||||
Its value must be an array of expressions. Example:
|
||||
|
||||
```js
|
||||
// Matches entities that BOTH have kind Component and type website
|
||||
{
|
||||
"$all": [
|
||||
{ "kind": "Component" },
|
||||
{ "spec.type": "website" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
An empty array always matches every entity.
|
||||
|
||||
- `$any`: Require that at least one of a set of expressions match a given entity.
|
||||
|
||||
Its value must be an array of expressions. Example:
|
||||
|
||||
```js
|
||||
// Matches entities that EITHER have kind Component or type website
|
||||
{
|
||||
"$any": [
|
||||
{ "kind": "Component" },
|
||||
{ "spec.type": "website" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
An empty array never matches anything.
|
||||
|
||||
- `$exists`: Assert on the existence of fields.
|
||||
|
||||
Its value is either `true`, meaning that the field must exist on the entity
|
||||
(no matter what its value), or `false`, meaning that it must not exist.
|
||||
Example:
|
||||
|
||||
```js
|
||||
// Matches entities that DO NOT have that annotation, ignoring what the
|
||||
// value might be
|
||||
{
|
||||
"metadata.annotations.backstage.io/orphan": {
|
||||
"$exists": false
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `$in`: Assert that a field has any of a set of primitive values.
|
||||
|
||||
Its value must be an array of string, number, and/or boolean values. Example:
|
||||
|
||||
```js
|
||||
// Matches entities whose type is EITHER service or website
|
||||
{
|
||||
"spec.type": {
|
||||
"$in": ["service", "website"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The matching is case insensitive. An empty array never matches anything.
|
||||
|
||||
- `$hasPrefix`: Assert that a field is a string that starts with a certain prefix text.
|
||||
|
||||
Its value is a string. Example:
|
||||
|
||||
```js
|
||||
// Matches entities whose project slug annotation starts with "backstage/"
|
||||
{
|
||||
"metadata.annotations.github.com/project-slug": {
|
||||
"$hasPrefix": "backstage/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The matching is case insensitive, and captures both exact matches and strings
|
||||
that start with the given prefix.
|
||||
|
||||
- `$contains`: Assert that an array contains an element that matches the given expression.
|
||||
|
||||
There is only limited support for this matcher. One use case is for relations:
|
||||
|
||||
```js
|
||||
{
|
||||
// Specifically type and (optionally) targetRef supported, and only
|
||||
// with equality or "$in" for the targetRef
|
||||
"relations": {
|
||||
"$contains": {
|
||||
"type": "ownedBy",
|
||||
"targetRef": {
|
||||
"$in": ["user:default/foo", "group:default/bar"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The other use case is for arrays where you match with a primitive value, such
|
||||
as tags. Example:
|
||||
|
||||
```js
|
||||
{
|
||||
// Works for array fields whose items are primitive values
|
||||
// (typically strings, but numbers and booleans are also supported)
|
||||
"metadata.tags": {
|
||||
"$contains": "java"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /entities`
|
||||
|
||||
Lists entities.
|
||||
|
||||
@@ -728,6 +728,49 @@ Notes:
|
||||
- Icons for groups and tabs are resolved via the app's IconsApi. When using a string icon id (for example `"dashboard"`), ensure that the corresponding icon bundles are enabled/installed in your app (see the [IconBundleBlueprint documentation](https://backstage.io/api/stable/variables/_backstage_plugin-app-react.IconBundleBlueprint.html)).
|
||||
- Group icons are only rendered if `showNavItemIcons` is set to `true`.
|
||||
|
||||
### Content ordering within groups
|
||||
|
||||
By default, content items within each group are sorted alphabetically by title. You can change this with the `contentOrder` option, which supports two modes:
|
||||
|
||||
- **`title`** (default) — sort alphabetically by the content extension's title (case-insensitive).
|
||||
- **`natural`** — preserve the natural extension discovery/registration order.
|
||||
|
||||
A page-level `contentOrder` sets the default for all groups, and individual groups can override it:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
extensions:
|
||||
- page:catalog/entity:
|
||||
config:
|
||||
# Default content order for all groups
|
||||
contentOrder: title
|
||||
|
||||
groups:
|
||||
- documentation:
|
||||
title: Docs
|
||||
# Override: keep natural order for this group
|
||||
contentOrder: natural
|
||||
```
|
||||
|
||||
Note that content ordering only applies to content items within groups. Ungrouped tabs (those not matching any group definition) always retain their natural order.
|
||||
|
||||
### Group aliases
|
||||
|
||||
Groups can declare `aliases` — a list of other group IDs that should be treated as equivalent. Any entity content extension targeting an aliased group ID will be included in the aliasing group. This is useful when renaming or merging groups without having to reconfigure individual extensions:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
extensions:
|
||||
- page:catalog/entity:
|
||||
config:
|
||||
groups:
|
||||
- develop:
|
||||
title: Develop
|
||||
# Content targeting 'development' will appear in this group
|
||||
aliases:
|
||||
- development
|
||||
```
|
||||
|
||||
### Overriding or disabling a tab's group (per extension)
|
||||
|
||||
Each entity content extension (tabs on the entity page) can declare a default `group` in code. You can override or disable this per installation in `app-config.yaml` using the extension's config:
|
||||
|
||||
@@ -1121,7 +1121,7 @@ Describes the following entity kind:
|
||||
| `apiVersion` | `backstage.io/v1alpha1` |
|
||||
| `kind` | `Resource` |
|
||||
|
||||
A resource describes the infrastructure a system needs to operate, like BigTable
|
||||
A Resource describes the infrastructure a system needs to operate, like BigTable
|
||||
databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
|
||||
components and systems allows to visualize resource footprint, and create
|
||||
tooling around them.
|
||||
|
||||
Reference in New Issue
Block a user