+
diff --git a/docs/auth/auth0/provider.md b/docs/auth/auth0/provider.md
index 6fb57a641b..e9393cfa0b 100644
--- a/docs/auth/auth0/provider.md
+++ b/docs/auth/auth0/provider.md
@@ -37,6 +37,8 @@ auth:
audience: ${AUTH_AUTH0_AUDIENCE}
connection: ${AUTH_AUTH0_CONNECTION}
connectionScope: ${AUTH_AUTH0_CONNECTION_SCOPE}
+ session:
+ secret: ${AUTH_SESSION_SECRET}
```
The Auth0 provider is a structure with three configuration keys:
@@ -46,6 +48,8 @@ The Auth0 provider is a structure with three configuration keys:
page
- `domain`: The Application domain, found on the Auth0 Application page
+Because Auth0 requires a session you need to give the session a secret key.
+
## Optional Configuration
- `audience`: The intended recipients of the token
diff --git a/docs/auth/index.md b/docs/auth/index.md
index 5702e96cee..fa185c0c23 100644
--- a/docs/auth/index.md
+++ b/docs/auth/index.md
@@ -150,6 +150,31 @@ const app = createApp({
});
```
+If the provider in auth backend expects additional headers such as `x-provider-token`, there is now a way to configure that in `ProxiedSignInPage` using the optional `headers` prop.
+
+Example:
+
+```tsx
+
+```
+
+Headers can also be returned in an async manner:
+
+```tsx
+
{
+ const someValue = await someFn();
+ return { 'x-some-key': someValue };
+ }}
+/>
+```
+
A downside of this method is that it can be cumbersome to set up for local development.
As a workaround for this, it's possible to dynamically select the sign-in page based on
what environment the app is running in, and then use a different sign-in method for local
diff --git a/docs/features/kubernetes/configuration.md b/docs/features/kubernetes/configuration.md
index 55843f3b24..41d72b2be2 100644
--- a/docs/features/kubernetes/configuration.md
+++ b/docs/features/kubernetes/configuration.md
@@ -31,6 +31,7 @@ kubernetes:
dashboardUrl: http://127.0.0.1:64713 # url copied from running the command: minikube service kubernetes-dashboard -n kubernetes-dashboard
dashboardApp: standard
caData: ${K8S_CONFIG_CA_DATA}
+ caFile: '' # local path to CA file
customResources:
- group: 'argoproj.io'
apiVersion: 'v1alpha1'
@@ -248,8 +249,8 @@ kubernetes:
##### `clusters.\*.caData` (optional)
Base64-encoded certificate authority bundle in PEM format. The Kubernetes client
-will verify that TLS certificate presented by the API server is signed by this
-CA.
+will verify that the TLS certificate presented by the API server is signed by
+this CA.
This value could be obtained via inspecting the kubeconfig file (usually
at `~/.kube/config`) under `clusters[*].cluster.certificate-authority-data`. For
@@ -265,6 +266,14 @@ See also
https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#environments-without-gcloud
for complete docs about GKE without `gcloud`.
+##### `clusters.\*.caFile` (optional)
+
+Filesystem path (on the host where the Backstage process is running) to a
+certificate authority bundle in PEM format. The Kubernetes client will verify
+that the TLS certificate presented by the API server is signed by this CA. Note
+that only clusters defined in the app-config via the [`config`](#config)
+cluster locator method can be configured in this way.
+
##### `clusters.\*.customResources` (optional)
Configures which [custom resources][3] to look for when returning an entity's
diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md
index 5cc2ab5f06..7267e9fd5b 100644
--- a/docs/features/search/how-to-guides.md
+++ b/docs/features/search/how-to-guides.md
@@ -1,8 +1,8 @@
---
id: how-to-guides
-title: Search "HOW TO" guides
-sidebar_label: "HOW TO" guides
-description: Search "HOW TO" guides
+title: Search How-To guides
+sidebar_label: How-To guides
+description: Search How To guides
---
## How to implement your own Search API
diff --git a/docs/features/search/search-engines.md b/docs/features/search/search-engines.md
index 35e17205ac..ccd8268dbe 100644
--- a/docs/features/search/search-engines.md
+++ b/docs/features/search/search-engines.md
@@ -117,7 +117,8 @@ within your instance. The configuration options are documented in the
The underlying functionality uses either the official ElasticSearch client
version 7.x (meaning that ElasticSearch version 7 is the only one confirmed to
-be supported), or the OpenSearch client, when the `aws` provider is configured.
+be supported), or the OpenSearch client, when the `aws` or `opensearch `provider
+is configured.
Should you need to create your own bespoke search experiences that require more
than just a query translator (such as faceted search or Relay pagination), you
@@ -200,6 +201,20 @@ search:
password: changeme
```
+### OpenSearch
+
+OpenSearch can be self hosted for example with the [official docker image](https://hub.docker.com/r/opensearchproject/opensearch). The configuration requires only the node and authentication.
+
+```yaml
+search:
+ elasticsearch:
+ provider: opensearch
+ node: http://0.0.0.0:9200
+ auth:
+ username: opensearch
+ password: changeme
+```
+
### Others
Other ElasticSearch instances can be connected to by using standard
diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md
index 3221b9e46a..afd9a0af93 100644
--- a/docs/features/software-catalog/api.md
+++ b/docs/features/software-catalog/api.md
@@ -154,6 +154,29 @@ Some more real world usable examples:
`/entities?fields=kind,metadata.namespace,metadata.name`
+### Ordering
+
+By default the entities are returned in an undefined, but stable order. You can
+pass in one or more `order` query parameters to affect that ordering.
+
+Each parameter starts either with `asc:` for ascending lexicographical order or
+`desc:` for descending (reverse) lexicographical order, followed by a
+dot-separated path into an entity's keys. The ordering is case insensitive. If
+more than one order directive is given, later directives have lower precedence
+(they are applied only when directives of higher precedence have equal values).
+
+Example:
+
+```text
+/entities?order=asc:kind&order=desc:metadata.name
+```
+
+This will order the output first by kind ascending, and then within each kind
+(if there's more than one of a given kind) by their name descending. When given
+a field that does NOT exist on all entities in the result set, those entities
+that do not have the field will always be sorted last in that particular order
+step, no matter what the desired order was.
+
#### Pagination
You may pass the `offset` and `limit` query parameters to do classical
diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md
index 27b26659cf..f0151d7618 100644
--- a/docs/features/software-catalog/descriptor-format.md
+++ b/docs/features/software-catalog/descriptor-format.md
@@ -703,7 +703,7 @@ spec:
name: Register
action: catalog:register
input:
- repoContentsUrl: '{{ steps.publish.output.repoContentsUrl }}'
+ repoContentsUrl: {{ steps['publish'].output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'
```
@@ -1309,3 +1309,7 @@ resolved relative to the location of this Location entity itself.
A list of targets as strings. They can all be either absolute paths/URLs
(depending on the type), or relative paths such as `./details/catalog-info.yaml`
which are resolved relative to the location of this Location entity itself.
+
+### `spec.presence` [optional]
+
+Describes whether the target of a location is required to exist or not. It defaults to `'required'` if not specified, can also be `'optional'`.
diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md
index e8176a688b..6b0e2330a4 100644
--- a/docs/features/software-templates/adding-templates.md
+++ b/docs/features/software-templates/adding-templates.md
@@ -76,7 +76,7 @@ spec:
name: Register
action: catalog:register
input:
- repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
+ repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'
```
diff --git a/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md b/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md
index a2277e096c..6e37a4df3e 100644
--- a/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md
+++ b/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md
@@ -169,14 +169,14 @@ These should be moved to `links` under the `output` object instead.
```diff
output:
-- remoteUrl: '{{ steps.publish.output.remoteUrl }}'
-- entityRef: '{{ steps.register.output.entityRef }}'
+- remoteUrl: {{ steps['publish'].output.remoteUrl }}
+- entityRef: {{ steps['register'].output.entityRef }}
+ links:
+ - title: Repository
-+ url: ${{ steps.publish.output.remoteUrl }}
++ url: ${{ steps['publish'].output.remoteUrl }}
+ - title: Open in catalog
+ icon: catalog
-+ entityRef: ${{ steps.register.output.entityRef }}
++ entityRef: ${{ steps['register'].output.entityRef }}
```
diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md
index 826121bd02..e5fdb034fb 100644
--- a/docs/features/software-templates/writing-templates.md
+++ b/docs/features/software-templates/writing-templates.md
@@ -88,17 +88,17 @@ spec:
name: Register
action: catalog:register
input:
- repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
+ repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'
# some outputs which are saved along with the job for use in the frontend
output:
links:
- title: Repository
- url: ${{ steps.publish.output.remoteUrl }}
+ url: ${{ steps['publish'].output.remoteUrl }}
- title: Open in catalog
icon: catalog
- entityRef: ${{ steps.register.output.entityRef }}
+ entityRef: ${{ steps['register'].output.entityRef }}
```
Let's dive in and pick apart what each of these sections do and what they are.
@@ -505,10 +505,10 @@ The main two that are used are the following:
output:
links:
- title: Repository
- url: ${{ steps.publish.output.remoteUrl }} # link to the remote repository
+ url: ${{ steps['publish'].output.remoteUrl }} # link to the remote repository
- title: Open in catalog
icon: catalog
- entityRef: ${{ steps.register.output.entityRef }} # link to the entity that has been ingested to the catalog
+ entityRef: ${{ steps['register'].output.entityRef }} # link to the entity that has been ingested to the catalog
```
## The templating syntax
diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md
index 4e806296e5..097d31f760 100644
--- a/docs/features/techdocs/configuration.md
+++ b/docs/features/techdocs/configuration.md
@@ -106,8 +106,20 @@ techdocs:
# If not set, the default location will be the root of the storage bucket
bucketRootPath: '/'
- # (Optional) An API key is required to write to a storage bucket.
- # If not set, environment variables or aws config file will be used to authenticate.
+ # (Optional) The AWS account ID where the storage bucket is located.
+ # Credentials for the account ID must be configured in the 'aws' app config section.
+ # See the integration-aws-node package for details on how to configure credentials in
+ # the 'aws' app config section.
+ # https://www.npmjs.com/package/@backstage/integration-aws-node
+ # If account ID is not set and no credentials are set, environment variables or aws config file will be used to authenticate.
+ # https://www.npmjs.com/package/@aws-sdk/credential-provider-node
+ # https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
+ accountId: ${TECHDOCS_AWSS3_ACCOUNT_ID}
+
+ # (Optional) AWS credentials to use to write to the storage bucket.
+ # This configuration section is now deprecated.
+ # Configuring the account ID is now preferred, with credentials in the 'aws' app config section.
+ # If credentials are not set and no account ID is set, environment variables or aws config file will be used to authenticate.
# https://www.npmjs.com/package/@aws-sdk/credential-provider-node
# https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
credentials:
diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md
index 70ea27821b..cfca7c6a7f 100644
--- a/docs/features/techdocs/how-to-guides.md
+++ b/docs/features/techdocs/how-to-guides.md
@@ -1,8 +1,8 @@
---
id: how-to-guides
-title: TechDocs "HOW TO" guides
-sidebar_label: "HOW TO" guides
-description: TechDocs "HOW TO" guides related to TechDocs
+title: TechDocs How-To guides
+sidebar_label: How-To guides
+description: TechDocs How-To guides related to TechDocs
---
## How to migrate from TechDocs Basic to Recommended deployment approach?
diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md
index 3ea57edc6b..f38a806413 100644
--- a/docs/features/techdocs/using-cloud-storage.md
+++ b/docs/features/techdocs/using-cloud-storage.md
@@ -244,10 +244,13 @@ techdocs:
type: 'awsS3'
awsS3:
bucketName: 'name-of-techdocs-storage-bucket'
+ accountId: '123456789012'
region: ${AWS_REGION}
- credentials:
- accessKeyId: ${AWS_ACCESS_KEY_ID}
- secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+aws:
+ accounts:
+ - accountId: '123456789012'
+ accessKeyId: ${AWS_ACCESS_KEY_ID}
+ secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
```
Refer to the
diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md
index fc5b02e6f4..0441d3f589 100644
--- a/docs/getting-started/configuration.md
+++ b/docs/getting-started/configuration.md
@@ -79,7 +79,7 @@ backend:
database:
- client: better-sqlite3
- connection: ':memory:'
-+ # config options: https://node-postgres.com/api/client
++ # config options: https://node-postgres.com/apis/client
+ client: pg
+ connection:
+ host: ${POSTGRES_HOST}
diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md
index 2d34998013..7db41d7768 100644
--- a/docs/getting-started/homepage.md
+++ b/docs/getting-started/homepage.md
@@ -84,8 +84,8 @@ Let's update the route for "Home" in the Backstage sidebar to point to the new h
- 
- | 
+ | |
+ |
| Before |
diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md
index 64f78c0997..8e130e7094 100644
--- a/docs/getting-started/keeping-backstage-updated.md
+++ b/docs/getting-started/keeping-backstage-updated.md
@@ -13,7 +13,7 @@ starting point that's meant to be evolved.
The Backstage CLI has a command to bump all `@backstage` packages and
dependencies you're using to the latest versions:
-[versions:bump](https://backstage.io/docs/cli/commands#versionsbump).
+[versions:bump](https://backstage.io/docs/local-dev/cli-commands#versionsbump).
```bash
yarn backstage-cli versions:bump
@@ -70,7 +70,7 @@ example, depends on global referential equality. This can cause problems in
Backstage with API lookup, or config loading.
To help resolve these situations, the Backstage CLI has
-[versions:check](https://backstage.io/docs/cli/commands#versionscheck). This
+[versions:check](https://backstage.io/docs/local-dev/cli-commands#versionscheck). This
will validate versions of `@backstage` packages in your app to check for
duplicate definitions:
diff --git a/docs/overview/logos.md b/docs/overview/logos.md
index 9421b7f31e..ac54640e33 100644
--- a/docs/overview/logos.md
+++ b/docs/overview/logos.md
@@ -21,7 +21,7 @@ The assets below are all in `.svg` format. Other formats are available in the
- 
+
## Backstage icon
@@ -37,6 +37,6 @@ The assets below are all in `.svg` format. Other formats are available in the
- 
+
diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md
index 10ffc82188..ad5421585e 100644
--- a/docs/overview/versioning-policy.md
+++ b/docs/overview/versioning-policy.md
@@ -1,7 +1,7 @@
---
id: versioning-policy
title: Release & Versioning Policy
-description:
+description: The process and policy for releasing and versioning Backstage
---
The Backstage project is comprised of a set of software components that together
diff --git a/docs/plugins/call-existing-api.md b/docs/plugins/call-existing-api.md
index e91506623b..da76fa8434 100644
--- a/docs/plugins/call-existing-api.md
+++ b/docs/plugins/call-existing-api.md
@@ -79,7 +79,7 @@ proxy:
```ts
// Inside your component
const backendUrl = config.getString('backend.baseUrl');
-fetch(`${backendUrl}/proxy/frobs/list`)
+fetch(`${backendUrl}/api/proxy/frobs/list`)
.then(response => response.json())
.then(payload => setFrobs(payload as Frob[]));
```
diff --git a/docs/plugins/integrating-search-into-plugins.md b/docs/plugins/integrating-search-into-plugins.md
index 3855dd5474..524daf18cd 100644
--- a/docs/plugins/integrating-search-into-plugins.md
+++ b/docs/plugins/integrating-search-into-plugins.md
@@ -333,3 +333,85 @@ reading the search context.
If you produce something generic and reusable, consider contributing your
component upstream so that all users of the Backstage Search Platform can
benefit. Issues and pull requests welcome.
+
+#### Custom search results
+
+Search results throughout Backstage are rendered as lists so that list items can easily be customized; although a [default result list item](https://backstage.io/storybook/?path=/story/plugins-search-defaultresultlistitem--default) is available, plugins are in the best position to provide custom result list items that surface relevant information only known to the plugin.
+
+The example below imagines `YourCustomSearchResult` as a type of search result that contains associated `tags` which could be rendered as chips below the title/text.
+
+```tsx
+import { Link } from '@backstage/core-components';
+import { useAnalytics } from '@backstage/core-plugin-api';
+import { ResultHighlight } from '@backstage/plugin-search-common';
+import { HighlightedSearchResultText } from '@backstage/plugin-search-react';
+
+type CustomSearchResultListItemProps = {
+ result: YourCustomSearchResult;
+ rank?: number;
+ highlight?: ResultHighlight;
+};
+
+export const CustomSearchResultListItem = (
+ props: CustomSearchResultListItemProps,
+) => {
+ const { title, text, location, tags } = props.result;
+
+ const analytics = useAnalytics();
+ const handleClick = () => {
+ analytics.captureEvent('discover', title, {
+ attributes: { to: location },
+ value: props.rank,
+ });
+ };
+
+ return (
+
+
+
+
+ ) : (
+ title
+ )
+ }
+ secondary={
+ highlight?.fields?.text ? (
+
+ ) : (
+ text
+ )
+ }
+ />
+ {tags &&
+ tags.map((tag: string) => (
+
+ ))}
+
+
+
+
+ );
+};
+```
+
+The optional use of the `` component makes it possible to highlight relevant parts of the result based on the user's search query.
+
+**Note on Analytics**: In order for app integrators to track and improve search experiences across Backstage, it's important for them to understand when and what users search for, as well as what they click on after searching. When providing a custom result component, it's your responsibility as a plugin developer to instrument it according to search analytics conventions. In particular:
+
+- You must use the `analytics.captureEvent` method, from the `useAnalytics()` hook (detailed [plugin analytics docs are here](./analytics.md)).
+- You must ensure that the action of the event, representing a click on a search result item, is `discover`, and the subject is the `title` of the clicked result. In addition, the `to` attribute should be set to the result's `location`, and the `value` of the event must be set to the `rank` (passed in as a prop).
+- You must ensure that the aforementioned `captureEvent` method is called when a user clicks the link; you should further ensure that the `noTrack` prop is added to the link (which disables default link click tracking, in favor of this custom instrumentation).
+
+For other examples and inspiration on custom result list items, check out the [``](https://github.com/backstage/backstage/blob/c981e83/plugins/stack-overflow/src/search/StackOverflowSearchResultListItem/StackOverflowSearchResultListItem.tsx) or [``](https://github.com/backstage/backstage/blob/c981e83/plugins/catalog/src/components/CatalogSearchResultListItem/CatalogSearchResultListItem.tsx) components.
diff --git a/docs/releases/v1.2.0-changelog.md b/docs/releases/v1.2.0-changelog.md
index 30c780e7ae..977f8a25b7 100644
--- a/docs/releases/v1.2.0-changelog.md
+++ b/docs/releases/v1.2.0-changelog.md
@@ -722,7 +722,7 @@
### Patch Changes
-- ac19f82936: Added ARIA landmark to Page component and added ARIA landmark