Merge branch 'master' into update-codeblocks

2023-03-08 10:07:11 -06:00
parent 9c95f91c0a 673292e273
commit 34fe6c9246
730 changed files with 15064 additions and 2592 deletions
@@ -176,7 +176,7 @@ By far, our most-used plugin is our TechDocs plugin, which we use for creating
 technical documentation. Our philosophy at Spotify is to treat "docs like code",
 where you write documentation using the same workflow as you write your code.
 This makes it easier to create, find, and update documentation.
-[TechDocs is now open source.](https://backstage.io/docs/features/techdocs/techdocs-overview)
+[TechDocs is now open source.](https://backstage.io/docs/features/techdocs/)
 (See also:
 "[Will Spotify's internal plugins be open sourced, too?](#will-spotifys-internal-plugins-be-open-sourced-too)"
 above)
@@ -18,7 +18,11 @@ Settings for local development:

 - Name: Backstage (or your custom app name)
 - Redirect URI: `http://localhost:7007/api/auth/gitlab/handler/frame`
- Scopes: `read_api` and `read_user`
+- Scopes: `read_user` for sign-in. If you also need ID tokens (e.g. if you are
+  using the Kubernetes plugin and have clusters with `authProvider: oidc` and
+  [`oidcTokenProvider:
+gitlab`](https://backstage.io/docs/features/kubernetes/configuration/#clustersoidctokenprovider-optional)),
+  add the `openid` scope.

 ## Configuration

@@ -5,7 +5,7 @@ title: Service to Service Auth
 description: This section describes how to use service to service authentication, both internally within Backstage plugins and towards external services.
 ---

-This article describes the steps needed to introduce _backend-to-backend auth_.
+This article describes the steps needed to introduce _service-to-service auth_ (formerly _backend-to-backend_ auth).
 This allows plugin backends to determine whether a given request originates from
 a legitimate Backstage plugin (or other external caller), by requiring a special
 type of service-to-service token which is signed with a shared secret.
@@ -60,7 +60,7 @@ backend:

 **NOTE**: For ease of development, we auto-generate a key for you if you haven't
 configured a secret in dev mode. You _must set your own secret_ in order for
-backend-to-backend auth to work in production; the `ServiceTokenManager` will
+service-to-service auth to work in production; the `ServiceTokenManager` will
 throw an exception in production if it has no keys to work with, which will lead
 to the backend failing to start up.

@@ -168,7 +168,61 @@ Whenever you want to allow modules to configure your plugin dynamically, for
 example in the way that the catalog backend lets catalog modules inject
 additional entity providers, you can use the extension points mechanism. This is
 described in detail with code examples in [the extension points architecture
-article](../architecture/05-extension-points.md).
+article](../architecture/05-extension-points.md), while the following is a more
+slim example of how to implement an extension point for a plugin:
+
+```ts
+import { createExtensionPoint } from '@backstage/backend-plugin-api';
+
+// This is the extension point interface, which is how modules interact with your plugin.
+export interface ExamplesExtensionPoint {
+  addExample(example: Example): void;
+}
+
+// This is the extension point reference that encapsulates the above interface.
+export const examplesExtensionPoint =
+  createExtensionPoint<ExamplesExtensionPoint>({
+    id: 'example.examples',
+  });
+
+// This is the implementation of the extension point, which is internal to your plugin.
+class ExamplesExtension implements ExamplesExtensionPoint {
+  #examples: Example[] = [];
+
+  addExample(example: Example): void {
+    this.#examples.push(example);
+  }
+
+  // Note that this method is internal to this implementation
+  getRegisteredExamples() {
+    return this.#examples;
+  }
+}
+
+// The following shows how your plugin would register the extension point
+// and use the features that other modules have registered.
+export const examplePlugin = createBackendPlugin({
+  pluginId: 'example',
+  register(env) {
+    const examplesExtensions = new ExamplesExtension();
+    env.registerExtensionPoint(examplesExtensionPoint, examplesExtensions);
+
+    env.registerInit({
+      deps: { logger: coreServices.logger },
+      async init({ logger }) {
+        // We can access `examplesExtension` directly, giving us access to the internal interface.
+        const examples = examplesExtension.getRegisteredExamples();
+
+        logger.info(`The following examples have been registered: ${examples}`);
+      },
+    });
+  },
+});
+```
+
+This is a very common type of extension point, one where modules are given the opportunity to register features to be used by the plugin. In this case modules are able to register examples that are then used by our examples plugin.
+
+Note that the public extension point interface only needs to expose the `addExample` method, while the `getRegisteredExamples()` method is kept internal to the plugin.

 ### Configuration

@@ -160,8 +160,9 @@ auth:
        audience: ${AUTH_OKTA_AUDIENCE}
 ```

-The following values are supported out-of-the-box by the frontend: `google`, `microsoft`,
-`okta`, `onelogin`.
+The following values are supported out-of-the-box by the frontend: `gitlab` (the
+application whose `clientId` is used by the auth provider should be granted the
+`openid` scope), `google`, `microsoft`, `okta`, `onelogin`.

 Take note that `oidcTokenProvider` is just the issuer for the token, you can use any
 of these with an OIDC enabled cluster, like using `microsoft` as the issuer for a EKS
@@ -255,7 +255,7 @@ i.e. not Backstage specific but the same as in Kubernetes.

 Each entity gets an automatically generated globally unique ID when it first
 enters the database. This field is not meant to be specified as input data, but
-is rater created by the database engine itself when producing the output entity.
+is rather created by the database engine itself when producing the output entity.

 Note that `uid` values are _not_ to be seen as stable, and should _not_ be used
 as external references to an entity. The `uid` can change over time even when a
@@ -14,7 +14,7 @@ websites, libraries, data pipelines, etc). The catalog is built around the
 concept of [metadata YAML files](descriptor-format.md) stored together with the
 code, which are then harvested and visualized in Backstage.

-![software-catalog](https://backstage.io/blog/assets/6/header.png)
+![software-catalog](../../assets/header.png)

 ## How it works

@@ -103,7 +103,7 @@ References for `createScaffolderFieldExtension` have an `/alpha` version of `cre
 /* highlight-remove-next-line */
 import { createScaffolderFieldExtension } from '@backstage/plugin-scaffolder';
 /* highlight-add-next-line */
-import { createNextScaffolderFieldExtension } from '@backstage/plugin-scaffolder/alpha';
+import { createNextScaffolderFieldExtension } from '@backstage/plugin-scaffolder-react/alpha';

 export const EntityNamePickerFieldExtension = scaffolderPlugin.provide(
  /* highlight-remove-next-line */
@@ -24,8 +24,53 @@ passed as `input` to the function.
 In `packages/backend/src/plugins/scaffolder/actions/custom.ts` we can create a
 new action.

-```ts
-import { createTemplateAction } from '@backstage/plugin-scaffolder-backend';
+```ts title="With Zod"
+import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
+import fs from 'fs-extra';
+import { z } from 'zod';
+
+export const createNewFileAction = () => {
+  return createTemplateAction({
+    id: 'mycompany:create-file',
+    schema: {
+      input: z.object({
+        contents: z.string().describe('The contents of the file'),
+        filename: z
+          .string()
+          .describe('The filename of the file that will be created'),
+      }),
+    },
+
+    async handler(ctx) {
+      await fs.outputFile(
+        `${ctx.workspacePath}/${ctx.input.filename}`,
+        ctx.input.contents,
+      );
+    },
+  });
+};
+```
+
+So let's break this down. The `createNewFileAction` is a function that returns a
+`createTemplateAction`, and it's a good place to pass in dependencies which
+close over the `TemplateAction`. Take a look at our
+[built-in actions](https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/actions/builtin)
+for reference.
+
+The `createTemplateAction` takes an object which specifies the following:
+
+- `id` - a unique ID for your custom action. We encourage you to namespace these
+  in some way so that they won't collide with future built-in actions that we
+  may ship with the `scaffolder-backend` plugin.
+- `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
+
+You can also choose to define your custom action using JSON schema instead of `zod`:
+
+```ts title="With JSON Schema"
+import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
 import fs from 'fs-extra';

 export const createNewFileAction = () => {
@@ -59,27 +104,6 @@ export const createNewFileAction = () => {
 };
 ```

-So let's break this down. The `createNewFileAction` is a function that returns a
-`createTemplateAction`, and it's a good place to pass in dependencies which
-close over the `TemplateAction`. Take a look at our
-[built-in actions](https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/actions/builtin)
-for reference.
-
-We set the type generic to `{ contents: string, filename: string }` which is
-there to set the type on the handler `ctx` `inputs` property so we get good type
-checking. This could be generated from the next part of this guide, the `input`
-schema, but it's not supported right now. Feel free to contribute 🚀 👍.
-
-The `createTemplateAction` takes an object which specifies the following:
-
- `id` - a unique ID for your custom action. We encourage you to namespace these
-  in some way so that they won't collide with future built-in actions that we
-  may ship with the `scaffolder-backend` plugin.
- `schema.input` - A JSON schema for input values to your function
- `schema.output` - A JSON schema for values which are outputted from the
-  function using `ctx.output`
- `handler` - the actual code which is run part of the action, with a context
-
 ### The context object

 When the action `handler` is called, we provide you a `context` as the only
@@ -89,10 +113,10 @@ argument. It looks like the following:
 - `ctx.logger` - a Winston logger for additional logging inside your action
 - `ctx.logStream` - a stream version of the logger if needed
 - `ctx.workspacePath` - a string of the working directory of the template run
- `ctx.input` - an object which should match the JSON schema provided in the
+- `ctx.input` - an object which should match the `zod` or JSON schema provided in the
  `schema.input` part of the action definition
 - `ctx.output` - a function which you can call to set outputs that match the
-  JSON schema in `schema.output` for ex. `ctx.output('downloadUrl', something)`
+  JSON schema or `zod` in `schema.output` for ex. `ctx.output('downloadUrl', myDownloadUrl)`
 - `createTemporaryDirectory` a function to call to give you a temporary
  directory somewhere on the runner so you can store some files there rather
  than polluting the `workspacePath`
@@ -8,7 +8,7 @@ description: TechDocs CLI - a utility command line interface for managing TechDo
 Utility command line interface for managing TechDocs sites in
 [Backstage](https://github.com/backstage/backstage).

-https://backstage.io/docs/features/techdocs/techdocs-overview
+https://backstage.io/docs/features/techdocs/

 ## Features

@@ -433,7 +433,7 @@ const app = createApp({

 ## How to add the documentation setup to your software templates

-[Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index)
+[Software Templates](https://backstage.io/docs/features/software-templates/)
 in Backstage is a tool that can help your users to create new components out of
 already configured templates. It comes with a set of default templates to use,
 but you can also
@@ -71,9 +71,9 @@ app
  good starting point for you to get to know Backstage.
 - **packages/backend/**: We include a backend that helps power features such as
  [Authentication](https://backstage.io/docs/auth/),
-  [Software Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview),
-  [Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index)
-  and [TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview)
+  [Software Catalog](https://backstage.io/docs/features/software-catalog/),
+  [Software Templates](https://backstage.io/docs/features/software-templates/)
+  and [TechDocs](https://backstage.io/docs/features/techdocs/)
  amongst other things.

 ### Troubleshooting
@@ -0,0 +1,66 @@
+---
+id: getting-involved
+title: Getting Involved
+# prettier-ignore
+description: How can you help us build Backstage? We welcome contributions of all kinds, from documentation to code to design.
+---
+
+We encourage contributions of all kinds, from documentation to code to design, here's some ideas on how you can help us build and improve Backstage!
+
+### Report bugs
+
+No one likes bugs. Report bugs as an issue [here](https://github.com/backstage/backstage/issues/new?template=bug_template.md).
+
+### Fix bugs or build new features
+
+Look through the GitHub issues for [bugs](https://github.com/backstage/backstage/labels/bug), [good first issues](https://github.com/backstage/backstage/labels/good%20first%20issue) or [help wanted](https://github.com/backstage/backstage/labels/help%20wanted).
+
+### Build a plugin
+
+The value of Backstage grows with every new plugin that gets added. Wouldn't it be fantastic if there was a plugin for every infrastructure project out there? We think so. And we would love your help.
+
+A great reference example of a plugin can be found on [our blog](https://backstage.io/blog/2020/04/06/lighthouse-plugin) (thanks [@fastfrwrd](https://github.com/fastfrwrd)!)
+
+What kind of plugins should/could be created? Some inspiration from the 120+ plugins that we have developed inside Spotify can be found [here](https://backstage.io/demos), but we will keep a running list of suggestions labeled with [[plugin]](https://github.com/backstage/backstage/labels/plugin).
+
+### Suggesting a plugin
+
+If you start developing a plugin that you aim to release as open source, we suggest that you create a [new Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development.
+
+You can also use this process if you have an idea for a good plugin but you hope that someone else will pick up the work.
+
+### Adding non-code Contributions
+
+Since there is such a large landscape of possible development, build, and deployment environments, we welcome community contributions in these areas in the [`/contrib`](https://github.com/backstage/backstage/tree/master/contrib) folder of the project. This is an excellent place to put things that help out the community at large, but which may not fit within the scope of the core product to support natively. Here, you will find Helm charts, alternative Docker images, and much more.
+
+### Write documentation or improve the website
+
+The current documentation is very limited. Help us make the `/docs` folder come alive.
+
+Docs are published to [backstage.io/docs](https://backstage.io/docs). If you
+contribute to the documentation, you might want to preview your changes before
+submitting them. You'll find the website sources under [/microsite](https://github.com/backstage/backstage/tree/master/microsite)
+with instructions for building and locally serving the website in the
+[README](/microsite#readme).
+
+### Contribute to Storybook
+
+We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://backstage.io/storybook).
+
+Either help us [create new components](https://github.com/backstage/backstage/labels/help%20wanted) or improve stories for the existing ones (look for files with `*.stories.tsx`).
+
+### Submit feedback
+
+The best way to send feedback is to file [an issue](https://github.com/backstage/backstage/issues).
+
+If you are proposing a feature:
+
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to implement.
+- Use appropriate labels
+- Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+### Add your company to `ADOPTERS`
+
+Have you started using Backstage? Adding your company to [ADOPTERS](https://github.com/backstage/backstage/blob/master/ADOPTERS.md) really helps the project, you can do this by filling out this [Adopter form](https://form.typeform.com/to/zcOaKikB).
@@ -31,4 +31,10 @@ catalog:
      yourProviderId:
        host: gitlab.com
        orgEnabled: true
+        group: org/teams # Optional. Must not end with slash. Accepts only groups under the provided path (which will be stripped)
+        groupPattern: '[\s\S]*' # Optional. Filters found groups based on provided pattern. Defaults to `[\s\S]*`, which means to not filter anything
 ```
+
+When the `group` parameter is provided, the corresponding path prefix will be stripped out from each matching group
+when computing the unique entity name. e.g. If `group` is `org/teams`, the name for `org/teams/avengers/gotg` will
+be `avengers-gotg`.
@@ -671,7 +671,7 @@ TypeScript support is currently handled though the `typesVersions` field, as the
 To add subpath exports to an existing package, simply add the desired `"exports"` fields and then run the following command:

 ```bash
-yarn backstage-cli package migrate package-exports
+yarn backstage-cli migrate package-exports
 ```

 ## Experimental Type Build
@@ -20,11 +20,11 @@ The permissions framework depends on a few other Backstage systems, which must b

 The permissions framework itself is new to Backstage and still evolving quickly. To ensure your version of Backstage has all the latest permission-related functionality, it’s important to upgrade to the latest version. The [Backstage upgrade helper](https://backstage.github.io/upgrade-helper/) is a great tool to help ensure that you’ve made all the necessary changes during the upgrade!

-### Enable backend-to-backend authentication
+### Enable service-to-service authentication

-Backend-to-backend authentication allows Backstage backend code to verify that a given request originates from elsewhere in the Backstage backend. This is useful for tasks like collation of catalog entities in the search index. This type of request shouldn’t be permissioned, so it’s important to configure this feature before trying to use the permissions framework.
+Service-to-service authentication allows Backstage backend code to verify that a given request originates from elsewhere in the Backstage backend. This is useful for tasks like collation of catalog entities in the search index. This type of request shouldn’t be permissioned, so it’s important to configure this feature before trying to use the permissions framework.

-To set up backend-to-backend authentication, follow the [backend-to-backend authentication docs](../tutorials/backend-to-backend-auth.md).
+To set up service-to-service authentication, follow the [service-to-service authentication docs](../auth/service-to-service-auth.md).

 ### Supply an identity resolver to populate group membership on sign in

@@ -146,7 +146,7 @@ Look at [DefaultTechDocsCollatorFactory test](https://github.com/backstage/backs

 #### 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).
+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/#plugins-integrated-with-backstage-search).

 ## Building a search experience into your plugin