diff --git a/docs/assets/uiguide/backstage-website-registered-catalog-view.png b/docs/assets/uiguide/backstage-website-registered-catalog-view.png new file mode 100644 index 0000000000..9263eff0c7 Binary files /dev/null and b/docs/assets/uiguide/backstage-website-registered-catalog-view.png differ diff --git a/docs/assets/uiguide/catalog-filter-options.png b/docs/assets/uiguide/catalog-filter-options.png new file mode 100644 index 0000000000..f2a85ab192 Binary files /dev/null and b/docs/assets/uiguide/catalog-filter-options.png differ diff --git a/docs/assets/uiguide/catalog-graph.png b/docs/assets/uiguide/catalog-graph.png new file mode 100644 index 0000000000..59e290b0f0 Binary files /dev/null and b/docs/assets/uiguide/catalog-graph.png differ diff --git a/docs/assets/uiguide/component-name-updated.png b/docs/assets/uiguide/component-name-updated.png new file mode 100644 index 0000000000..602e2e551a Binary files /dev/null and b/docs/assets/uiguide/component-name-updated.png differ diff --git a/docs/assets/uiguide/confirm-unregister-entity.png b/docs/assets/uiguide/confirm-unregister-entity.png new file mode 100644 index 0000000000..89a565ff35 Binary files /dev/null and b/docs/assets/uiguide/confirm-unregister-entity.png differ diff --git a/docs/assets/uiguide/curve-monotone.png b/docs/assets/uiguide/curve-monotone.png new file mode 100644 index 0000000000..52275ec780 Binary files /dev/null and b/docs/assets/uiguide/curve-monotone.png differ diff --git a/docs/assets/uiguide/curve-step-before.png b/docs/assets/uiguide/curve-step-before.png new file mode 100644 index 0000000000..a9aa4c8e6f Binary files /dev/null and b/docs/assets/uiguide/curve-step-before.png differ diff --git a/docs/assets/uiguide/details-for-registered-backstage-website.png b/docs/assets/uiguide/details-for-registered-backstage-website.png new file mode 100644 index 0000000000..00d55026f2 Binary files /dev/null and b/docs/assets/uiguide/details-for-registered-backstage-website.png differ diff --git a/docs/assets/uiguide/details-system-entity.png b/docs/assets/uiguide/details-system-entity.png new file mode 100644 index 0000000000..c667421603 Binary files /dev/null and b/docs/assets/uiguide/details-system-entity.png differ diff --git a/docs/assets/uiguide/enter-name-of-new-component.png b/docs/assets/uiguide/enter-name-of-new-component.png new file mode 100644 index 0000000000..fc6a11a360 Binary files /dev/null and b/docs/assets/uiguide/enter-name-of-new-component.png differ diff --git a/docs/assets/uiguide/enter-url-of-component.png b/docs/assets/uiguide/enter-url-of-component.png new file mode 100644 index 0000000000..29fecb7bfd Binary files /dev/null and b/docs/assets/uiguide/enter-url-of-component.png differ diff --git a/docs/assets/uiguide/entities-owned-by-me.png b/docs/assets/uiguide/entities-owned-by-me.png new file mode 100644 index 0000000000..e0dda5e680 Binary files /dev/null and b/docs/assets/uiguide/entities-owned-by-me.png differ diff --git a/docs/assets/uiguide/entity-actions.png b/docs/assets/uiguide/entity-actions.png new file mode 100644 index 0000000000..3c725758e4 Binary files /dev/null and b/docs/assets/uiguide/entity-actions.png differ diff --git a/docs/assets/uiguide/error-creating-new-component.png b/docs/assets/uiguide/error-creating-new-component.png new file mode 100644 index 0000000000..8c7da95159 Binary files /dev/null and b/docs/assets/uiguide/error-creating-new-component.png differ diff --git a/docs/assets/uiguide/error-message-catalog-info-file-deleted.png b/docs/assets/uiguide/error-message-catalog-info-file-deleted.png new file mode 100644 index 0000000000..7526ba65aa Binary files /dev/null and b/docs/assets/uiguide/error-message-catalog-info-file-deleted.png differ diff --git a/docs/assets/uiguide/example-website-relationships.png b/docs/assets/uiguide/example-website-relationships.png new file mode 100644 index 0000000000..b4fa6e33c7 Binary files /dev/null and b/docs/assets/uiguide/example-website-relationships.png differ diff --git a/docs/assets/uiguide/filter-by-name.png b/docs/assets/uiguide/filter-by-name.png new file mode 100644 index 0000000000..ca0336eadc Binary files /dev/null and b/docs/assets/uiguide/filter-by-name.png differ diff --git a/docs/assets/uiguide/max-depth-1.png b/docs/assets/uiguide/max-depth-1.png new file mode 100644 index 0000000000..d353b8ae23 Binary files /dev/null and b/docs/assets/uiguide/max-depth-1.png differ diff --git a/docs/assets/uiguide/max-depth-infinite.png b/docs/assets/uiguide/max-depth-infinite.png new file mode 100644 index 0000000000..0f72cccb84 Binary files /dev/null and b/docs/assets/uiguide/max-depth-infinite.png differ diff --git a/docs/assets/uiguide/new-tutorial-component-in-software-catalog.png b/docs/assets/uiguide/new-tutorial-component-in-software-catalog.png new file mode 100644 index 0000000000..51ee73c524 Binary files /dev/null and b/docs/assets/uiguide/new-tutorial-component-in-software-catalog.png differ diff --git a/docs/assets/uiguide/portal-with-annotations.png b/docs/assets/uiguide/portal-with-annotations.png new file mode 100644 index 0000000000..a8c9bc535b Binary files /dev/null and b/docs/assets/uiguide/portal-with-annotations.png differ diff --git a/docs/assets/uiguide/review-select-import.png b/docs/assets/uiguide/review-select-import.png new file mode 100644 index 0000000000..bd4a0acd7c Binary files /dev/null and b/docs/assets/uiguide/review-select-import.png differ diff --git a/docs/assets/uiguide/select-advanced-options.png b/docs/assets/uiguide/select-advanced-options.png new file mode 100644 index 0000000000..27fe7c7b16 Binary files /dev/null and b/docs/assets/uiguide/select-advanced-options.png differ diff --git a/docs/assets/uiguide/select-create-for-new-component.png b/docs/assets/uiguide/select-create-for-new-component.png new file mode 100644 index 0000000000..9fbc612ac0 Binary files /dev/null and b/docs/assets/uiguide/select-create-for-new-component.png differ diff --git a/docs/assets/uiguide/select-create-to-make-component.png b/docs/assets/uiguide/select-create-to-make-component.png new file mode 100644 index 0000000000..e86e9398ca Binary files /dev/null and b/docs/assets/uiguide/select-create-to-make-component.png differ diff --git a/docs/assets/uiguide/select-delete-entity.png b/docs/assets/uiguide/select-delete-entity.png new file mode 100644 index 0000000000..6874c5e83d Binary files /dev/null and b/docs/assets/uiguide/select-delete-entity.png differ diff --git a/docs/assets/uiguide/select-edit-icon-for-component.png b/docs/assets/uiguide/select-edit-icon-for-component.png new file mode 100644 index 0000000000..04d693259d Binary files /dev/null and b/docs/assets/uiguide/select-edit-icon-for-component.png differ diff --git a/docs/assets/uiguide/select-example-website.png b/docs/assets/uiguide/select-example-website.png new file mode 100644 index 0000000000..f8f72699eb Binary files /dev/null and b/docs/assets/uiguide/select-example-website.png differ diff --git a/docs/assets/uiguide/select-register-existing-component.png b/docs/assets/uiguide/select-register-existing-component.png new file mode 100644 index 0000000000..8d3f5c7af4 Binary files /dev/null and b/docs/assets/uiguide/select-register-existing-component.png differ diff --git a/docs/assets/uiguide/select-review-create-component.png b/docs/assets/uiguide/select-review-create-component.png new file mode 100644 index 0000000000..5acce27ec6 Binary files /dev/null and b/docs/assets/uiguide/select-review-create-component.png differ diff --git a/docs/assets/uiguide/select-unregister-entity-from-three-dots.png b/docs/assets/uiguide/select-unregister-entity-from-three-dots.png new file mode 100644 index 0000000000..959ec3f544 Binary files /dev/null and b/docs/assets/uiguide/select-unregister-entity-from-three-dots.png differ diff --git a/docs/assets/uiguide/select-view-graph.png b/docs/assets/uiguide/select-view-graph.png new file mode 100644 index 0000000000..79886a82b4 Binary files /dev/null and b/docs/assets/uiguide/select-view-graph.png differ diff --git a/docs/assets/uiguide/setup-nodejs-cat-owner.png b/docs/assets/uiguide/setup-nodejs-cat-owner.png new file mode 100644 index 0000000000..5e8effec72 Binary files /dev/null and b/docs/assets/uiguide/setup-nodejs-cat-owner.png differ diff --git a/docs/assets/uiguide/simplify-off-merge-relations-off.png b/docs/assets/uiguide/simplify-off-merge-relations-off.png new file mode 100644 index 0000000000..d999a7a5c7 Binary files /dev/null and b/docs/assets/uiguide/simplify-off-merge-relations-off.png differ diff --git a/docs/assets/uiguide/simplify-off-merge-relations-on.png b/docs/assets/uiguide/simplify-off-merge-relations-on.png new file mode 100644 index 0000000000..1003f2dd3d Binary files /dev/null and b/docs/assets/uiguide/simplify-off-merge-relations-on.png differ diff --git a/docs/assets/uiguide/simplify-on-merge-relations-off.png b/docs/assets/uiguide/simplify-on-merge-relations-off.png new file mode 100644 index 0000000000..60cbe0107e Binary files /dev/null and b/docs/assets/uiguide/simplify-on-merge-relations-off.png differ diff --git a/docs/assets/uiguide/simplify-on-merge-relations-on.png b/docs/assets/uiguide/simplify-on-merge-relations-on.png new file mode 100644 index 0000000000..d72489b50e Binary files /dev/null and b/docs/assets/uiguide/simplify-on-merge-relations-on.png differ diff --git a/docs/assets/uiguide/successful-create-new-component.png b/docs/assets/uiguide/successful-create-new-component.png new file mode 100644 index 0000000000..658189b7d2 Binary files /dev/null and b/docs/assets/uiguide/successful-create-new-component.png differ diff --git a/docs/assets/uiguide/tutorial-catalog-info-yaml-file.png b/docs/assets/uiguide/tutorial-catalog-info-yaml-file.png new file mode 100644 index 0000000000..55d3d24baf Binary files /dev/null and b/docs/assets/uiguide/tutorial-catalog-info-yaml-file.png differ diff --git a/docs/assets/uiguide/tutorial-component-open-in-catalog.png b/docs/assets/uiguide/tutorial-component-open-in-catalog.png new file mode 100644 index 0000000000..107974c437 Binary files /dev/null and b/docs/assets/uiguide/tutorial-component-open-in-catalog.png differ diff --git a/docs/assets/uiguide/updated-component-name-in-ui.png b/docs/assets/uiguide/updated-component-name-in-ui.png new file mode 100644 index 0000000000..7b5a9e5648 Binary files /dev/null and b/docs/assets/uiguide/updated-component-name-in-ui.png differ diff --git a/docs/getting-started/create-a-component.md b/docs/getting-started/create-a-component.md index 29ba99db83..b4e5c6ab19 100644 --- a/docs/getting-started/create-a-component.md +++ b/docs/getting-started/create-a-component.md @@ -6,38 +6,92 @@ description: Leverage the scaffolder to start creating components with best prac Audience: Developers -## Summary +## Overview -This guide will walk you through how to use Software Templates to create new components with baked in best practices. +Components can be created in the Software Catalog using software templates. Templates load skeletons of code, which can include some variables, and incorporate your company's best practices. The templates are published to a location, such as GitHub or GitLab. + +The standalone Backstage application includes the `Example Node.js Template`, which is an example template for the scaffolder that creates and registers a simple Node.js service. You can also [create your own templates](../features/software-templates/adding-templates.md). ## Prerequisites -:::note +For this example, the default Node.js template will be used. The template creates a repository in GitHub and adds the necessary files to it so that the component is integrated into the Software Catalog. Because you are creating a repository, you must first create an integration between Backstage and GitHub. -If you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to use the templates feature. One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: `export NODE_OPTIONS=--no-node-snapshot` +- You should have already [installed a standalone app](./index.md). -::: +- Register the [GitHub Scaffolder Action module](../features/software-templates/builtin-actions.md#installing-action-modules). -You should already have [a standalone app](./index.md). +- [Set up a GitHub Integration](../getting-started/config/authentication.md#setting-up-a-github-integration) with Backstage, using a GitHub Personal Access Token. -You will also need to register the [GitHub Scaffolder Action module](../features/software-templates/builtin-actions.md#installing-action-modules) before moving forward. +## Creating the component -## Creating your component +To create the component: -- Go to `create` and choose to create a website with the `Example Node.js Template` -- Type in a name, let's use `tutorial` and click `Next Step` +1. Select `Create`. -![Software template deployment input screen asking for a name](../assets/getting-started/b-scaffold-1.png) + ![select create for new component](../assets/uiguide/select-create-for-new-component.png) -- You should see the following screen: +2. Select `Service` in the `CATEGORIES` dropdown list. +3. Select the `Owner`. For this example, you can select `guest`. +4. Select `Choose` in the `Example Node.js Template`. -![Software template deployment input screen asking for the GitHub username, and name of the new repo to create](../assets/getting-started/b-scaffold-2.png) + ![setup-nodejs-categories-owners](../assets/uiguide/setup-nodejs-cat-owner.png) -- For host, it should default to github.com -- As owner, type your GitHub username -- For the repository name, type `tutorial`. Go to the next step +5. For this example, enter `tutorial` for the `Name` of the service and select `NEXT`. -- Review the details of this new service, and press `Create` if you want to - deploy it like this. -- You can follow along with the progress, and as soon as every step is - finished, you can take a look at your new service + ![enter name of new component](../assets/uiguide/enter-name-of-new-component.png) + +6. Enter your GitHub user name as the `Owner`. +7. Enter `tutorial` for the `Repository` and select `REVIEW`. + + ![select review create component](../assets/uiguide/select-review-create-component.png) + +8. Review the information and select `CREATE`. + + ![select create to make component](../assets/uiguide/select-create-to-make-component.png) + +If you see an error message, similar to the following, + + ![error creating new component](../assets/uiguide/error-creating-new-component.png) + +Perform the following steps: + +1. Close the Backstage app. +2. Enter `CTRL-C` in the terminal window to stop the Backstage frontend and backend. +3. In the terminal window, enter: + + ``` + export NODE_OPTIONS=--no-node-snapshot + ``` + + > **NOTE:** + > The [no-node-snapshot](../features/software-templates/index.md#prerequisites) `NODE_OPTIONS` environment variable is required in order to use the templates. + +4. Enter `yarn start` to restart the Backstage application. +5. Repeat steps to create the component. + +Otherwise, you can follow along with the progress, and as soon as every step is finished, you can take a look at your new service in either the repository or the Catalog. + +![run of example of create component](../assets/uiguide/successful-create-new-component.png) + +Selecting `REPOSITORY` displays the `catalog-info.yaml`file and other project setup files that were created for the new component in the main branch of the `tutorial` repository. + +The `catalog-info.yaml` file describes the entity for the Software Catalog. [Descriptor Format of Catalog Entities](../features/software-catalog/descriptor-format.md) provides additional information. + +``` + apiVersion: backstage.io/v1alpha1 + kind: Component + metadata: + name: "tutorial" + spec: + type: service + owner: user:guest + lifecycle: experimental +``` + +Selecting `OPEN IN CATALOG` displays details of the new component, such as its relationships, links, and subcomponents. + +![select open in catalog](../assets/uiguide/tutorial-component-open-in-catalog.png) + +Selecting `Home` in the sidebar, displays the new `tutorial` component in the Catalog. + +![new tutorial component in software catalog](../assets/uiguide/new-tutorial-component-in-software-catalog.png) diff --git a/docs/getting-started/filter-catalog.md b/docs/getting-started/filter-catalog.md new file mode 100644 index 0000000000..3e0de8cdeb --- /dev/null +++ b/docs/getting-started/filter-catalog.md @@ -0,0 +1,57 @@ +--- +id: filter-catalog +title: Filtering the Catalog +description: Filtering the Catalog. +--- + +Audience: All + +## Overview + +The Catalog can be filtered by any combination of owner, kind, type, lifecycle, processing status, namespace, and name. [Customize Filters](../features/software-catalog/catalog-customization.md#customize-filters) provides information on how to modify the available filter criteria. + +![Catalog filter options](../assets/uiguide/catalog-filter-options.png) + +The [Technical Overview](../overview/technical-overview.md#software-catalog-system-model) provides a description of the types of entities displayed in the Catalog. + +## Filtering the Catalog + +You can filter the Catalog using a combination of the following: + +- **Filter by name** + + Enter one or more consecutive letters into the `Filter` field. As you type the letters, the entities whose names do not contain that string will be filtered out of the displayed list. + + ![Filter catalog by name](../assets/uiguide/filter-by-name.png) + +- **Filter by kind** + + Use the `Kind` dropdown list to select which kind of entity to show in the list: + + - API + - Component + - Group + - Location + - System + - Template + - User + +- **Filter by Type** + + Use the `Type` dropdown list to select which type of entity to show in the list. The selections available in the dropdown list depend on the kind of entity selected in the `Kind` list, and the types of entity you have registered for that kind. + +- **Filter by Owner** + + Use the `Owner` dropdown to filter the Catalog list by who owns the entity. + +- **Filter by Lifecycle** + + Use the `Lifecycle` dropdown to filter the Catalog list by lifecycle. + +- **Filter by Processing Status** + + Use the `Processing Status` dropdown to restrict the displayed list to only include those entities which are [orphaned](../features/software-catalog/life-of-an-entity.md#orphaning) or [in error](../features/software-catalog/life-of-an-entity.md#errors). + +- **Filter by Namespace** + + Use the `Namespace` dropdown to filter the catalog list by namespace associated with the entity. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index d7c4ee96c8..5893877a55 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -184,8 +184,14 @@ Choose the correct next steps for your user role, if you're likely to be deployi - Using your Backstage instance - [Logging into Backstage](./logging-in.md) + - [Viewing the Catalog](./viewing-catalog.md) + - [Viewing what you own](./view-what-you-own.md) + - [Viewing entity relationships](./viewing-entity-relationships.md) + - [Filtering the Catalog](./filter-catalog.md) - [Register a component](./register-a-component.md) - [Create a new component](./create-a-component.md) + - [Update a component](./update-a-component.md) + - [Unregistering and deleting a component](./unregister-delete-component.md) Share your experiences, comments, or suggestions with us: [on discord](https://discord.gg/backstage-687207715902193673), file issues for any diff --git a/docs/getting-started/register-a-component.md b/docs/getting-started/register-a-component.md index 4e2076ee8d..1f2fda2871 100644 --- a/docs/getting-started/register-a-component.md +++ b/docs/getting-started/register-a-component.md @@ -8,38 +8,53 @@ Audience: Developers :::note Note Entity files are stored in YAML format, if you are not familiar with YAML, you can learn more about it [here](https://yaml.org). + +[Descriptor Format of Catalog Entities](../features/software-catalog/descriptor-format.md) provides additional information on the format of the YAML entity files. ::: -## Summary +## Overview This guide will walk you through how to pull Backstage data from other locations manually. There are integrations that will automatically do this for you. +When registering a component, you can: + +- Link to an existing entity file: The file is analyzed to determine which entities are defined, and the entities are added to the Scaffolded Backstage App Catalog. For example, `https://github.com/backstage/backstage/blob/master/catalog-info.yaml`. + +- Link to a repository: All `catalog-info.yaml` files are discovered in the repository and their defined entities are added to the Scaffolded Backstage App Catalog. For example, `https://github.com/backstage/backstage`. + + :::note Note + If no entities are found, a Pull Request is created that adds an example `catalog-info.yaml` file to the repository. When the Pull Request is merged, the Scaffolded Backstage App Catalog loads all of the defined entities. + + ::: + ## Prerequisites -You should have already [have a standalone app](./index.md). +- You should have already [installed a standalone app](./index.md). -## 1. Finding our template +## Registering a component -Register a new component, by going to `create` and choose `Register existing component` +To manually register a component in the Software Catalog: - +1. Select `Create`. +2. Select `REGISTER EXISTING COMPONENT`. -![Software template main screen, with a blue button to add an existing component](../assets/getting-started/b-existing-1.png) + ![Select Register existing component.](../assets/uiguide/select-register-existing-component.png) -## 2. Filling out the template +3. Fill out the template. -For repository URL, use `https://github.com/backstage/backstage/blob/master/catalog-info.yaml`. This is used in our [demo site](https://demo.backstage.io) catalog. + The standalone Backstage application includes one template. For this example, enter the repository URL to the entity file, `https://github.com/backstage/backstage/blob/master/catalog-info.yaml`. This is used in the Backstage [demo site](https://demo.backstage.io) catalog. -![Register a new component wizard, asking for an URL to the existing component YAML file](../assets/getting-started/b-existing-2.png) + ![enter url of component entity file.](../assets/uiguide/enter-url-of-component.png) -Hit `Analyze` and review the changes. +4. Select `ANALYZE`. +5. If the changes from `ANALYZE` are correct, select `IMPORT`. -## 3. Import the entity + ![review and select import.](../assets/uiguide/review-select-import.png) -If the changes from `Analyze` are correct, click `Apply`. + If your entity was successfully imported, the details will be displayed. -![Register a new component wizard, showing the metadata for the component YAML we use in this tutorial](../assets/getting-started/b-existing-3.png) + ![details of registered component.](../assets/uiguide/details-for-registered-backstage-website.png) -You should receive a message that your entities have been added. +6. Select `Home` to view your new entity in the Software Catalog. -If you go back to `Home`, you should be able to find `backstage`. You can click it and see the details for this new entity. + ![Backstage website component in software catalog.](../assets/uiguide/backstage-website-registered-catalog-view.png) diff --git a/docs/getting-started/unregister-delete-component.md b/docs/getting-started/unregister-delete-component.md new file mode 100644 index 0000000000..f8034bf3ed --- /dev/null +++ b/docs/getting-started/unregister-delete-component.md @@ -0,0 +1,66 @@ +--- +id: unregister-delete-component +title: Unregistering and deleting a component +description: Unregistering and deleting a component from the catalog +--- + +Audience: Developers + +## Overview + +URLs to YAML files that you registered either using the `Create` button or by adding to your app-config file are both handled by entity providers. + +[Implicit deletion](../features/software-catalog/life-of-an-entity.md#implicit-deletion) occurs when an entity provider issues a deletion of an entity. That entity, as well as the entire tree of entities processed out of it are considered for immediate deletion. + +However, you are also able to manually unregister an entity from the Catalog or perform a direct, [explicit deletion](../features/software-catalog/life-of-an-entity.md#explicit-deletion) of individual entities. + +## Unregistering an entity + +You can unregister an entity so it will not be displayed in the Catalog but still keep its `catalog-info.yaml` file in the repository. This provides the ability to register the entity with the Catalog again in the future. + +To unregister an entity: + +1. In the Catalog, select the entity you want to unregister. In this example, `mytutorial` is being unregistered. + +2. Select the three dots. + +3. Select `Unregister entity` in the dropdown menu. + + ![Screenshot of selecting unregister entity.](../assets/uiguide/select-unregister-entity-from-three-dots.png) + +4. Select `UNREGISTER LOCATION`. The entity is removed from the Catalog. + + ![Screenshot of confirming unregister entity.](../assets/uiguide/confirm-unregister-entity.png) + +## Deleting an entity + +You can also delete an entity from the Catalog. However, this requires that you also delete the `catalog-info.yaml` entity definition file associated with the entity. + +To delete an entity: + +1. Delete the following entity definition files for the entity in the repository: + + - catalog-info.yaml + - index.js + - package.json + +2. In the Backstage App Catalog view, select the entity being deleted. In this example, `mytutorial` is being deleted. + + Since you have deleted the entity definition files, an error is displayed that states the `catalog-info.yaml` file cannot be found. + + ![Screenshot of error finding catalog info yaml file.](../assets/uiguide/error-message-catalog-info-file-deleted.png) + +3. Select the three dots. +4. Select `Unregister entity` in the dropdown menu. + + ![Screenshot of selecting unregister entity.](../assets/uiguide/select-unregister-entity-from-three-dots.png) + +5. Select `ADVANCED OPTIONS`. + + ![Screenshot of selecting advanced options.](../assets/uiguide/select-advanced-options.png) + +6. Select `DELETE ENTITY`. + + ![Screenshot of selecting delete entity.](../assets/uiguide/select-delete-entity.png) + +A confirmation message that the entity has been successfully deleted is briefly displayed. The entity is no longer displayed in the Catalog. diff --git a/docs/getting-started/update-a-component.md b/docs/getting-started/update-a-component.md new file mode 100644 index 0000000000..ffe21bc8b3 --- /dev/null +++ b/docs/getting-started/update-a-component.md @@ -0,0 +1,33 @@ +--- +id: update-a-component +title: Update a Component +description: Update an existing component. +--- + +Audience: Developers + +## Overview + +Components in the Software Catalog are created using a software template. The template generates a `catalog-info.yaml` file in either GitHub or GitLab that defines the entity. To update the component, you must edit its corresponding `catalog-info.yaml` entity definition file. + +## Updating the component + +To update a component using the Backstage UI: + +1. Select the "Edit" icon associated with the component. In this example, the `tutorial` entity is selected. + + ![select edit icon for component](../assets/uiguide/select-edit-icon-for-component.png) + + The associated `catalog-info.yaml` file is displayed. + + ![tutorial component catalog-info.yaml file](../assets/uiguide/tutorial-catalog-info-yaml-file.png) + +2. Make your changes to the YAML file. In this example, the name of the component is changed to `mytutorial`. + + ![component name updated](../assets/uiguide/component-name-updated.png) + +3. Select `Commit changes` to commit your changes to the appropriate branch and go through your normal PR review procedure. + +4. Once the updated `catalog-info.yaml` file has been merged into the branch associated with the component, then you will see the updated information in the Software Catalog. + + ![updated component name in ui](../assets/uiguide/updated-component-name-in-ui.png) diff --git a/docs/getting-started/view-what-you-own.md b/docs/getting-started/view-what-you-own.md new file mode 100644 index 0000000000..fc8b1feeae --- /dev/null +++ b/docs/getting-started/view-what-you-own.md @@ -0,0 +1,22 @@ +--- +id: view-what-you-own +title: Viewing what you own +description: View the entities that you own either directly or through a group +--- + +Audience: All + +You can own entities either directly or through a group that you're part of. + +To view the entities that you own: + +1. Select `Home` in the sidebar. +2. Select `User` in the `Kind` dropdown list. +3. Select your username in the `All Users` list. + +A page is displayed that shows the entities of which you have ownership, either directly, or through a group of which you are a member. You can toggle between showing: + +- `Direct Relations` - entities that you directly own +- `Aggregated Relations` - entities that you own through your group + +![Screenshot of the Backstage portal entities owned by guest user.](../assets/uiguide/entities-owned-by-me.png) diff --git a/docs/getting-started/viewing-catalog.md b/docs/getting-started/viewing-catalog.md new file mode 100644 index 0000000000..acfa470cc2 --- /dev/null +++ b/docs/getting-started/viewing-catalog.md @@ -0,0 +1,85 @@ +--- +id: viewing-catalog +title: Viewing the Catalog +sidebar_label: Viewing the Catalog +description: Viewing the Catalog +--- + +Audience: All + +## Overview + +Initially, when you log into your standalone Backstage App, `Home` is selected in the sidebar, which displays the Catalog in the main panel. + +There are four main entities that you should become familiar with: + +- `Components` - Individual pieces of software that can be tracked in source control and can implement APIs for other components to consume. +- `Resources` - The physical or virtual infrastructure needed to operate a component. +- `Systems` - A collection of resources and components that cooperate to perform a function by exposing one or several public APIs. It hides the resources and private APIs between the components from the consumer. +- `Domains` - A collection of systems that share terminology, domain models, metrics, KPIs, business purpose, or documentation. + +The [Technical Overview](../overview/technical-overview.md#software-catalog-system-model) provides a description of all of the types of entities displayed in the Catalog. + +It should be noted that you can also [create your own kinds of entities](../features/software-catalog/extending-the-model.md#adding-a-new-kind), if you need to model something in your organization that does not map to one of the existing entity types. + +Initially, the Catalog displays registered entities matching the following filter settings: + +- `Kind` - Component +- `Type` - all +- `Owner` - Owned +- `Lifecycle` - list of [lifecycle](../features/software-catalog/descriptor-format.md#speclifecycle-required-1) values of entities in the Catalog +- `Processing Status` - normal +- `Namespace` - The ID of a [namespace](../features/software-catalog/descriptor-format.md#namespace-optional) to which the entity belongs + +You can change the initial setting for the [Owner](../features/software-catalog/catalog-customization.md#initially-selected-filter) and [Kind](../features/software-catalog/catalog-customization.md#initially-selected-kind) filters. + +## Informational columns for each entity + +For each kind of entity, a set of columns display information regarding the entity. For example, the default set of information for a `Component` is: + +- `Name` - the name of the component +- `System` - an optional field that references the system to which the component belongs +- `Owner` - the owner of the component +- `Type` - common types are as follows, but you can [create a new type](../features/software-catalog/extending-the-model.md#adding-a-new-type-of-an-existing-kind) to meet your organization's needs + - `service` - a backend service, typically exposing an API + - `website` - a website + - `library` - a software library, such as an npm module or a Java library +- `Lifecycle` + - `experimental` - an experiment or early, non-production component, signaling + that users may not prefer to consume it over other more established + components, or that there are low or no reliability guarantees + - `production` - an established, owned, maintained component + - `deprecated` - a component that is at the end of its lifecycle, and may + disappear at a later point in time +- `Description` - an optional field that describes the component. +- `Tags` - an optional field that can be used for searching +- `Actions` - see [Catalog Actions](#catalog-actions) + +You can modify the columns associated with each kind of entity, following the instructions in [Customize Columns](../features/software-catalog/catalog-customization.md#customize-columns). + +## Catalog Actions + +For each entity, there are a set of actions that are available. + +![Screenshot explaining entity actions.](../assets/uiguide/entity-actions.png) + +From left to right, the actions are: + +- View - View the `catalog-info.yaml` file that defines the entity. +- Edit - Edit the `catalog-info.yaml` file that defines the entity. See [Updating a Component](../getting-started/update-a-component.md) +- Star - Designate the entity as a favorite. You can [filter](../getting-started/filter-catalog.md) the catalog for starred entities. + +[Customize Actions](../features/software-catalog/catalog-customization.md#customize-actions) describes how you can modify the actions that are displayed. + +## Viewing entity details + +Selecting an entity in the main panel displays details of the entity. The type of details depends on the type of entity. For example, selecting a Component, such as `example-website`, displays the following details: + +- `About` - Metadata for the entity, such as description, owner, tags, and domain. +- `Relations` - see [Viewing entity relationships](../getting-started/viewing-entity-relationships.md) +- `Links` - any links associated with the entity +- `Has subcomponents` - An entity reference to another component of which the component is a part + +Selecting a System, such as `examples`, displays `About`, `Relations`, and `Links` similar to a Component, but it also includes `Has components`, `APIs` and `Has Resources`. + +![Details of system entity.](../assets/uiguide/details-system-entity.png) diff --git a/docs/getting-started/viewing-entity-relationships.md b/docs/getting-started/viewing-entity-relationships.md new file mode 100644 index 0000000000..c791ab5bc7 --- /dev/null +++ b/docs/getting-started/viewing-entity-relationships.md @@ -0,0 +1,98 @@ +--- +id: viewing-entity-relationships +title: Viewing entity relationships +description: View the relationships between the entities in the Catalog +--- + +Audience: All + +Each of the entities in the Catalog has various relationships to each other. For example, the demo data includes an API that provides data to a website. `guests` is the owner of the API and the website, and anyone signed in as part of the `guests` group can maintain them. + +To see these relationships: + +1. Select the name of the component in the main panel, in this example, `example-website`. + + ![Screenshot of the Backstage portal with example-website selected.](../assets/uiguide/select-example-website.png) + + A page is displayed that includes a `Relations` section. This section displays the selected entity and any other types of entities to which it is related. Each relationship is also designated, such as `hasPart/partOf` and `apiProvidedBy/providesApi`. [Well-known Relations between Catalog Entities](../features/software-catalog/well-known-relations.md) describes the most common relationships, but you can also [create your own relationships](../features/software-catalog/extending-the-model.md#adding-a-new-relation-type). + +2. Selecting any of the related entities allows you to drill down further through the system model. + + ![Screenshot of the example-website Relations panel.](../assets/uiguide/example-website-relationships.png) + +## Filtering the relationships + +You can also view the relationships in the [Catalog Graph](../features/software-catalog/creating-the-catalog-graph.md). This view allows you to filter what entities and relationships to display. + +To display the Catalog Graph: + +1. Select the name of the component in the main panel, in this example, `example-website`. + + A page is displayed that includes a `Relations` section. + +2. Select `View graph` in the `Relations` section. + + ![Select View graph.](../assets/uiguide/select-view-graph.png) + + The `Catalog Graph` is displayed. + + ![Screenshot of Catalog Graph.](../assets/uiguide/catalog-graph.png) + +### Setting the filters + +The `Catalog Graph` automatically reflects any changes you make to the filter settings. You can set the following filters: + +- `MAX DEPTH` + + - `MAX DEPTH` = 1 + + ![Max Depth at 1](../assets/uiguide/max-depth-1.png) + + - `MAX DEPTH` = infinite + + ![Max Depth at infinite](../assets/uiguide/max-depth-infinite.png) + +- `KINDS` - select what kinds of entities you want to view, default is all kinds +- `RELATIONS` - select which relationships you want to view, default is all relationships +- `Direction` - orientation in which you want to view the entity and its associated nodes + - Top to bottom + - Bottom to top + - Left to right + - Right to left +- `Curve` + + - `Curve` = Monotone + + ![Curve at Monotone.](../assets/uiguide/curve-monotone.png) + + - `Curve` = Step Before + + ![Curve at Step Before.](../assets/uiguide/curve-step-before.png) + +You can also toggle: + +- `Simplified` + - On = simple view + - Off = detailed view +- `Merge relations` + + - On = You see the relationship from the selected entity to the nodes and from the nodes to the selected entity. + - Off = You only see relations from the selected entity to its nodes. + + The following graphics illustrate the view of the nodes and relationships, based on the combination of the settings of `Simplified` and `Merge relations`. + + - `Simplified` = On and `Merge Relations` = On + + ![Simplified is On and Merge Relations is On.](../assets/uiguide/simplify-on-merge-relations-on.png) + + - `Simplified` = On and `Merge Relations` = Off + + ![Simplified is On and Merge Relations is Off.](../assets/uiguide/simplify-on-merge-relations-off.png) + + - `Simplified` = Off and `Merge Relations` = On + + ![Simplified is Off and Merge Relations is On.](../assets/uiguide/simplify-off-merge-relations-on.png) + + - `Simplified` = Off and `Merge Relations` = Off + + ![Simplified is Off and Merge Relations is Off.](../assets/uiguide/simplify-off-merge-relations-off.png) diff --git a/docs/landing-page/doc-landing-page.md b/docs/landing-page/doc-landing-page.md index 8697144bd8..98a0ad9fb9 100644 --- a/docs/landing-page/doc-landing-page.md +++ b/docs/landing-page/doc-landing-page.md @@ -33,13 +33,26 @@ description: Documentation landing page. Configure, Deploy, & Upgrade.

@@ -60,7 +73,7 @@ description: Documentation landing page.
  • Search
  • Software Catalog
  • Software Templates (aka Scaffolder)
    • -
  • TechDocs
    • +
  • TechDocs - a docs-like-code solution
    • diff --git a/microsite/sidebars.ts b/microsite/sidebars.ts index e07a1db123..7e4e41591b 100644 --- a/microsite/sidebars.ts +++ b/microsite/sidebars.ts @@ -69,8 +69,16 @@ export default { ]), sidebarElementWithIndex({ label: 'Using Backstage' }, [ 'getting-started/logging-in', - 'getting-started/register-a-component', - 'getting-started/create-a-component', + 'getting-started/viewing-catalog', + 'getting-started/view-what-you-own', + 'getting-started/viewing-entity-relationships', + 'getting-started/filter-catalog', + sidebarElementWithIndex({ label: 'Managing Components' }, [ + 'getting-started/register-a-component', + 'getting-started/create-a-component', + 'getting-started/update-a-component', + 'getting-started/unregister-delete-component', + ]), ]), 'overview/support', 'getting-started/keeping-backstage-updated', diff --git a/mkdocs.yml b/mkdocs.yml index c18d74494a..618f77a59f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,7 @@ plugins: nav: - Overview: - What is Backstage?: 'overview/what-is-backstage.md' + - Technical overview: 'overview/technical-overview.md' - Architecture overview: 'overview/architecture-overview.md' - Project Roadmap: 'overview/roadmap.md' - Vision: 'overview/vision.md' @@ -37,8 +38,15 @@ nav: - Kubernetes: 'deployment/k8s.md' - Using Backstage: - Logging in: 'getting-started/logging-in.md' - - Register a component: 'getting-started/register-a-component.md' - - Create a component: 'getting-started/create-a-component.md' + - Viewing the Catalog: 'getting-started/viewing-catalog.md' + - Viewing what you own: 'getting-started/view-what-you-own.md' + - Viewing entity relationships: 'getting-started/viewing-entity-relationships.md' + - Filtering the Catalog: 'getting-started/filter-catalog.md' + - Managing Components: + - Register a component: 'getting-started/register-a-component.md' + - Create a component: 'getting-started/create-a-component.md' + - Update a component: 'getting-started/update-a-component.md' + - Unregister/delete a component: 'getting-started/unregister-delete-component.md' - Keeping Backstage Updated: 'getting-started/keeping-backstage-updated.md' - Core Features: - Software Catalog: