Merge remote-tracking branch 'upstream/master' into aadazurecli

docs/auth/okta/provider.md

@@ -41,6 +41,8 @@ auth:
         clientId: ${AUTH_OKTA_CLIENT_ID}
         clientSecret: ${AUTH_OKTA_CLIENT_SECRET}
         audience: ${AUTH_OKTA_DOMAIN}
+        authServerId: ${AUTH_OKTA_AUTH_SERVER_ID} # Optional
+        idp: ${AUTH_OKTA_IDP} # Optional
 ```
 
 The values referenced are found on the Application page on your Okta site.
@@ -48,8 +50,10 @@ The values referenced are found on the Application page on your Okta site.
 - `clientId`: The client ID that you generated on Okta, e.g.
   `3abe134ejxzF21HU74c1`
 - `clientSecret`: The client secret shown for the Application.
-- `audience`: The Okta domain shown for your Application, e.g.
+- `audience`: The Okta domain shown for the Application, e.g.
   `https://company.okta.com`
+- `authServerId`: The authorization server ID for the Application
+- `idp`: The identity provider for the application, e.g. `0oaulob4BFVa4zQvt0g3`
 
 ## Adding the provider to the Backstage frontend
 

docs/features/kubernetes/configuration.md

@@ -57,10 +57,17 @@ This is an array used to determine where to retrieve cluster configuration from.
 
 Valid cluster locator methods are:
 
+- [`localKubectlProxy`](#localKubectlProxy)
 - [`config`](#config)
 - [`gke`](#gke)
 - [custom `KubernetesClustersSupplier`](#custom-kubernetesclusterssupplier)
 
+#### `localKubectlProxy`
+
+This cluster locator method will assume a locally running [`kubectl proxy`](https://kubernetes.io/docs/tasks/extend-kubernetes/http-proxy-access-api/#using-kubectl-to-start-a-proxy-server) process using the default port (8001).
+
+NOTE: This cluster locator method is for local development only and should not be used in production.
+
 #### `config`
 
 This cluster locator method will read cluster information from your app-config

docs/features/search/how-to-guides.md

@@ -112,6 +112,8 @@ of the `SearchType` component.
 </Paper>
 ```
 
+> 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 limit what can be searched in the Software Catalog
 
 The Software Catalog includes a wealth of information about the components,

docs/features/software-catalog/external-integrations.md

@@ -57,7 +57,7 @@ The recommended way of instantiating the catalog backend classes is to use the
 `CatalogBuilder`, as illustrated in the
 [example backend here](https://github.com/backstage/backstage/blob/master/packages/backend/src/plugins/catalog.ts).
 We will create a new
-[`EntityProvider`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/api/provider.ts)
+[`EntityProvider`](https://github.com/backstage/backstage/blob/master/plugins/catalog-node/src/api/provider.ts)
 subclass that can be added to this catalog builder.
 
 Let's make a simple provider that can refresh a set of entities based on a
@@ -79,7 +79,7 @@ import { Entity } from '@backstage/catalog-model';
 import {
   EntityProvider,
   EntityProviderConnection,
-} from '@backstage/plugin-catalog-backend';
+} from '@backstage/plugin-catalog-node';
 
 /**
  * Provides entities from fictional frobs service.
@@ -354,7 +354,7 @@ The recommended way of instantiating the catalog backend classes is to use the
 `CatalogBuilder`, as illustrated in the
 [example backend here](https://github.com/backstage/backstage/blob/master/packages/backend/src/plugins/catalog.ts).
 We will create a new
-[`CatalogProcessor`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/api/processor.ts)
+[`CatalogProcessor`](https://github.com/backstage/backstage/blob/master/plugins/catalog-node/src/api/processor.ts)
 subclass that can be added to this catalog builder.
 
 It is up to you where you put the code for this new processor class. For quick
@@ -371,7 +371,7 @@ import {
   CatalogProcessor,
   CatalogProcessorEmit,
   LocationSpec,
-} from '@backstage/plugin-catalog-backend';
+} from '@backstage/plugin-catalog-node';
 
 // A processor that reads from the fictional System-X
 export class SystemXReaderProcessor implements CatalogProcessor {
@@ -455,7 +455,7 @@ import {
   CatalogProcessorCache,
   CatalogProcessorParser,
   LocationSpec,
-} from '@backstage/plugin-catalog-backend';
+} from '@backstage/plugin-catalog-node';
 
 // It's recommended to always bump the CACHE_KEY version if you make
 // changes to the processor implementation or CacheItem.

docs/features/software-catalog/well-known-annotations.md

@@ -242,13 +242,14 @@ that entity if the periskop plugin is installed.
 # Example:
 metadata:
   annotations:
-    sentry.io/project-slug: pump-station
+    sentry.io/project-slug: backstage/pump-station
 ```
 
 The value of this annotation is the so-called slug (or alternatively, the ID) of
-a [Sentry](https://sentry.io) project within your organization. The organization
-slug is currently not configurable on a per-entity basis, but is assumed to be
-the same for all entities in the catalog.
+a [Sentry](https://sentry.io) project within your organization. The value can
+be the format of `[organization]/[project-slug]` or just `[project-slug]`. When
+the organization slug is omitted the `app-config.yaml` will be used as a
+fallback (`sentry.organization`).
 
 Specifying this annotation may enable Sentry related features in Backstage for
 that entity.

docs/features/techdocs/README.md

@@ -66,6 +66,7 @@ See [TechDocs Architecture](architecture.md) to get an overview of where the bel
 | GitHub Enterprise            | Yes ✅         |
 | Bitbucket                    | Yes ✅         |
 | Azure DevOps                 | Yes ✅         |
+| Gerrit                       | Yes ✅         |
 | GitLab                       | Yes ✅         |
 | GitLab Enterprise            | Yes ✅         |
 

docs/integrations/github/github-apps.md

@@ -79,7 +79,7 @@ privateKey: |
 ### Including in Integrations Config
 
 Once the credentials are stored in a YAML file generated by `create-github-app`,
-or manually by following the [GitHub Enterprise](#gitHub-enterprise)
+or manually by following the [GitHub Enterprise](#github-enterprise)
 instructions, they can be included in the `app-config.yaml` under the
 `integrations` section.
 

docs/integrations/ldap/org.md

@@ -12,6 +12,10 @@ groups - directly from an LDAP compatible service. The result is a hierarchy of
 [`Group`](../../features/software-catalog/descriptor-format.md#kind-group) kind
 entities that mirror your org setup.
 
+## Supported vendors
+
+Backstage in general supports OpenLDAP compatible vendors, as well as Active Directory and FreeIPA. If you are using a vendor that does not seem to be supported, please [file an issue](https://github.com/backstage/backstage/issues/new?assignees=&labels=enhancement&template=feature_template.md).
+
 ## Installation
 
 This guide will use the Entity Provider method. If you for some reason prefer

docs/overview/versioning-policy.md

@@ -49,7 +49,7 @@ functionality, breaking changes, and bug fixes, according the
 [versioning policy](#release-versioning-policy).
 
 Patch versions will only be released to address critical bug fixes. They are not
-bound to the regular cadence and are instead releases whenever needed.
+bound to the regular cadence and are instead released whenever needed.
 
 ## Next Release Line
 

docs/plugins/composability.md

@@ -74,7 +74,7 @@ The extension type is a simple one:
 
 ```ts
 export type Extension<T> = {
-  expose(plugin: BackstagePlugin<any, any>): T;
+  expose(plugin: BackstagePlugin): T;
 };
 ```
 

docs/plugins/integrating-search-into-plugins.md

@@ -14,7 +14,139 @@ Search Platform in your plugin.
 
 ## Providing data to the search platform
 
-> A guide on how to create collators is coming soon!
+### Create a collator
+
+> Knowing what a [collator](../features/search/concepts.md#collators) is will help you as you build it out.
+
+Imagine you have a plugin that is responsible for storing FAQ snippets in a database. You want other engineers to be able to easily find your questions and answers. So that means you want them to be indexed by the search platform. Lets say the FAQ snippets can be viewed at a URL like `backstage.example.biz/faq-snippets`.
+
+The search platform provides an interface (`DocumentCollatorFactory` from package `@backstage/plugin-search-common`) that allows you to do exactly that. It works by registering each of your entries as a "document" that later represents one search result each.
+
+> You can always look at a working example, e.g. [StackOverflowQuestionsCollatorFactory](https://github.com/backstage/backstage/blob/master/plugins/stack-overflow-backend/src/search/StackOverflowQuestionsCollatorFactory.ts), if you are unsure or want to follow best practices.
+
+#### 1. Install collator interface dependencies
+
+We will need the interface `DocumentCollatorFactory` from package `@backstage/plugin-search-common`, so let's add it to your plugins dependencies:
+
+```sh
+# navigate to the plugin directory
+# (for this tutorial our plugin lives in the backstage repo, if your plugin lives in a separate repo you need to clone that first)
+cd plugins/faq-snippets
+
+# Create a new branch using Git command-line
+git checkout -b tutorials/new-faq-snippets-collator
+
+# Install the package containing the interface
+yarn add @backstage/plugin-search-common
+```
+
+#### 2. Define your document type
+
+Before we can start generating documents from our FAQ entries, we first have to define a document type containing all necessary information we need to later display our entry as search result. The package `@backstage/plugin-search-common` we installed earlier contains a type `IndexableDocument` that we can extend.
+
+Create a new file `plugins/faq-snippets/src/search/collators/FaqSnippetDocument.ts` and paste the following below:
+
+```ts
+import { IndexableDocument } from '@backstage/plugin-search-common';
+
+export interface FaqSnippetDocument extends IndexableDocument {
+  answered_by: string;
+}
+```
+
+#### 3. Use Backstage App configuration
+
+Your new collator could benefit from using configuration directly from the Backstage `app-config.yaml` file which is located on the project's root folder:
+
+```yaml
+faq:
+  baseUrl: https://backstage.example.biz/faq-snippets
+```
+
+#### 4. Implement your collator
+
+Imagine your FAQs can be retrieved at the URL `https://backstage.example.biz/faq-snippets` with following JSON response format:
+
+```json
+{
+  "items": [
+    {
+      "id": 42,
+      "question": "What is The Answer to the Ultimate Question of Life, the Universe, and Everything?",
+      "answer": "Forty-two",
+      "user": "Deep Thought"
+    }
+  ]
+}
+```
+
+Below we provide an example implementation of how the FAQ collator factory could look like using our new document type, placed in the `plugins/faq-snippets/src/search/collators/FaqCollatorFactory.ts` file:
+
+```ts
+import fetch from 'cross-fetch';
+import { Logger } from 'winston';
+import { Config } from '@backstage/config';
+import { Readable } from 'stream';
+import { DocumentCollatorFactory } from '@backstage/plugin-search-common';
+
+import { FaqDocument } from './FaqDocument';
+
+export type FaqCollatorFactoryOptions = {
+  baseUrl?: string;
+  logger: Logger;
+};
+
+export class FaqCollatorFactory implements DocumentCollatorFactory {
+  private readonly baseUrl: string | undefined;
+  private readonly logger: Logger;
+  public readonly type: string = 'faq-snippets';
+
+  private constructor(options: FaqCollatorFactoryOptions) {
+    this.baseUrl = options.baseUrl;
+    this.logger = options.logger;
+  }
+
+  static fromConfig(config: Config, options: FaqCollatorFactoryOptions) {
+    const baseUrl =
+      config.getOptionalString('faq.baseUrl') ||
+      'https://backstage.example.biz/faq-snippets';
+    return new FaqCollatorFactory({ ...options, baseUrl });
+  }
+
+  async getCollator() {
+    return Readable.from(this.execute());
+  }
+
+  async *execute(): AsyncGenerator<FaqDocument> {
+    if (!this.baseUrl) {
+      this.logger.error(`No faq.baseUrl configured in your app-config.yaml`);
+      return;
+    }
+
+    const response = await fetch(this.baseUrl);
+    const data = await response.json();
+
+    for (const faq of data.items) {
+      yield {
+        title: faq.question,
+        location: `/faq-snippets/${faq.id}`,
+        text: faq.answer,
+        answered_by: faq.user,
+      };
+    }
+  }
+}
+```
+
+#### 5. Test your collator
+
+To verify your implementation works as expected make sure to add tests for it. For your convenience, there is the [`TestPipeline`](https://backstage.io/docs/reference/plugin-search-backend-node.testpipeline) utility that emulates a pipeline into which you can integrate your custom collator.
+
+Look at [DefaultTechDocsCollatorFactory test](https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/src/search/DefaultTechDocsCollatorFactory.test.ts), for an example.
+
+#### 6. Make your plugins collator discoverable for others
+
+If you want to make your collator discoverable for other adopters, add it to the list of [plugins integrated to search](https://backstage.io/docs/features/search/search-overview#plugins-integrated-with-backstage-search).
 
 ## Building a search experience into your plugin