From 3276260077a52fd733032bf9959446b2e905559b Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Tue, 21 Mar 2023 17:00:24 -0500 Subject: [PATCH 1/9] add an initial catalog user guide Signed-off-by: Waldir Montoya --- docs/assets/software-catalog/entity.svg | 4 ++++ docs/features/software-catalog/user-guide.md | 0 2 files changed, 4 insertions(+) create mode 100644 docs/assets/software-catalog/entity.svg create mode 100644 docs/features/software-catalog/user-guide.md diff --git a/docs/assets/software-catalog/entity.svg b/docs/assets/software-catalog/entity.svg new file mode 100644 index 0000000000..32fb9d3f3f --- /dev/null +++ b/docs/assets/software-catalog/entity.svg @@ -0,0 +1,4 @@ + + + +
Envelop
Envelop
ApiVersion
version of the spec
ApiVersion...
Kind
entity type
Kind...
Spec
Describes the entity
Spec...
Metadata
Thins that are not part of the spec
Metadata...
name
name
description
description
title
title
uid
uid
namespace
namespace
labels
labels
annotations
annotations
tags
tags
links
links
Entity
EntityText is not SVG - cannot display \ No newline at end of file diff --git a/docs/features/software-catalog/user-guide.md b/docs/features/software-catalog/user-guide.md new file mode 100644 index 0000000000..e69de29bb2 From 33befe22a218176f8ce9be7aead2e02d04f22a0a Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Tue, 21 Mar 2023 17:08:51 -0500 Subject: [PATCH 2/9] add Catalog User Guide Signed-off-by: Waldir Montoya --- docs/features/software-catalog/user-guide.md | 99 ++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/docs/features/software-catalog/user-guide.md b/docs/features/software-catalog/user-guide.md index e69de29bb2..75870bdb81 100644 --- a/docs/features/software-catalog/user-guide.md +++ b/docs/features/software-catalog/user-guide.md @@ -0,0 +1,99 @@ +#Architecting your Catalog + +## Overview + +The Software Catalog in Backstage is intended to capture entities relevant to humans and have a clear mental model around them rather than an exhaustive inventory of all possible things. The focus is on attaching functionality and visual views centered around these entities. Determining the "edge" where the catalog ends and the external world begins is crucial to ensure that the catalog's scope is appropriate. +The Backstage software catalog is a centralized hub for organizing and discovering software components and services. However, there may not be better tools for keeping track of the dynamic relationships between these components and services in real-time. Its primary objective is to offer a high-level overview of concepts rather than runtime aspects and to provide a user-friendly interface. To integrate data from external sources, it is recommended to attach tooling to the nodes in the graph using annotations. A front-end plugin can also be developed to showcase deployment information and other real-time data. +It is worth noting that the Backstage database should not be considered the ultimate source of truth. Instead, it is advisable to use the Backstage Catalog as a caching mechanism that utilizes a REST API to convey information to the catalog UI and other Backstage plugins. Adopting a GitOps approach is recommended to modify YAML files in Backstage, treating YAML files in repositories as the primary source of truth and using Scaffolder to make changes via the UI and generate a pull request in the repository with the updated changes. + +### Descriptor Components used to build the Catalog Graph + +**Entities:** An entity refers to a node in the graph that represents a distinct object, concept, or thing. Nodes are the fundamental building blocks of a graph database and are used to represent entities and their properties. + +![](../../assets/software-catalog/entity.svg) + +**Kinds:** These are broad categories used to group related entities. Kinds are used to provide a high-level categorization of entities, such as "service", "database", or "team". Kinds are often used to provide a way to filter entities in the catalog and to provide a high-level overview of the types of entities that are being managed. + +**Relations:** These are links between different entities in the catalog. Relations express the relationships between different entities, such as dependencies or ownership. Adopters can use relations to help users navigate the catalog and understand the relationships between different entities. + +**Spec:** A specification or "spec" is a schema that outlines the data structure of an entity in the Backstage catalog. It defines the properties, relationships, data types, and constraints for an entity, ensuring consistency and accuracy of data while allowing for easy sharing and consumption of data across components and plugins. Specs are useful when creating or extending entities and can help make data more reusable and interoperable. The spec section is fully customizable, and users can create their own components and plugins to render the information. + +**Types:** These are more specific categories used to classify entities within a given Kind. Types provide a more granular categorization of entities, such as "frontend-service" or "backend-service.". Types are often used to provide additional context and information about an entity and to help users understand the role and function of the entity within the broader system. + +**Annotations:** These key-value pairs can be attached to an entity in the catalog. They are typically used to add additional information or metadata to an entity. Annotations are often used to provide information that is used by automated tools or scripts and to provide further context to humans working with the entity or refer plugins to the external world. + +**Statuses:** These indicators represent an entity's current state. They are typically used to show whether an entity is healthy or not, whether it is up-to-date or out-of-date, or whether it is passing or failing various checks or tests. + +## Use cases out of the box + +The catalog builds a graph using descriptors as nodes and relations as edges. Out of the box you get the following use cases: + +- Ownership tracking +- Inventory +- Search +- Lifecycle tracking +- Tracking of real-time information sources +- Dependency mapping +- API exposure + +## Tracking Assets + +The recommended approach would be to represent information in catalog-info files, which the users themselves can manage. While automated classification based on repository contents can be helpful, it is recommended to use it only to generate the initial file and then allow humans to maintain it manually. The reason is that automation can sometimes fail, and it is essential to ensure the accuracy and reliability of this metadata. In short, humans should govern this piece of metadata to maintain its integrity. + +### Well-known trackable assets + +**Software Components** + +- Services +- Websites +- Libraries +- Data Pipelines +- Machine Learning Models +- Third-party software components: It is recommended to have a separate repo for all 3d party catalog-info files. + +**Systems** + +- Jira installation +- Pageduty +- Physical resources: This is probably more useful for longer-lived ones (eg, servers). + +**Ownership - users - groups by** + +- Business units +- Team +- Product area + +**Naming strategies:** + +- Ldap: Internal ldap usernames as entity names. e.g., owner: user:myuser or user: my-team-name. + +**Ownership strategies:** + +**Ownership based on teams:** The concept of ownership in the system is team-centric; hence, the "owner" field must reference the LDAP name of a squad according to a prescribed set of regulations. While there may be instances where the ownership is attributed to an individual, such deviations might create challenges. In such cases, the user could receive a notification through the web interface, highlighting that this departure is an exception and needs rectification. To ensure adherence to this system, every entity in the model should have a designated owner, preferably a valid team within the LDAP hierarchy. + +**Ownership of features:** To track the ownership of specific features within your products and their interrelationships, two options are available: introducing a new component type, such as "feature," or creating a new Kind altogether. Nonetheless, it is advisable to choose the former approach and introduce a new type, like "feature," is advisable as it is less complicated and poses a lower risk. + +**LDAP doesn’t reflect the organization structure:** If Workday or a similar system serves as the source of truth, and LDAP is utilized for user attributes, it is advisable to develop a layer on top of various systems to establish a unified API that the entire organization can query, rather than only Backstage. + +**APIs** + +- OpenApi +- AsyncApi +- graphQL +- gRPC + +APIs Could list networked services or libraries and it’s particularly useful to identify APIs that form boundaries between systems. There are some considerations to keep in mind: + +**API versions:** It’s not recommended to have multiple entity instances (e.g., metadata.name: my-api-v1 and metadata.name: my-api-v2). + +**Detail:** It’s not recommended going too granular because the catalog in its current form won't perhaps be a great platform to express it. + +**Relationships between APIs:** The idea is that you have a service component that exposes an api and then, it's not the api that consumes the other api, it's the component that consumes the other api. + +**Backend for front end API (BFF):** The suggestion is to create separate components for the frontend and backend services, with the frontend component having a type of "website" and the backend component having a type of "service". This is because the BFF API is tailored for a specific UI and is not meant to be used by others, making it unnecessary to include in the catalog. + +**API registry:** The exploration of all APIs within an organization is a typical use case for an API registry. + +## Reference models + +**C4 model:** For inspiration, you could review the [C4 model](https://c4model.com/), which defines a pattern for visualizing software architecture. From e44261e3b4ddd587449fdddf27116868e6e4e3d8 Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Wed, 22 Mar 2023 09:58:04 -0500 Subject: [PATCH 3/9] Fix misspelling Signed-off-by: Waldir Montoya --- docs/assets/software-catalog/.$entity.svg.bkp | 4 ++++ docs/assets/software-catalog/entity.svg | 2 +- docs/features/software-catalog/user-guide.md | 4 ++-- 3 files changed, 7 insertions(+), 3 deletions(-) create mode 100644 docs/assets/software-catalog/.$entity.svg.bkp diff --git a/docs/assets/software-catalog/.$entity.svg.bkp b/docs/assets/software-catalog/.$entity.svg.bkp new file mode 100644 index 0000000000..a7b6fb1d7e --- /dev/null +++ b/docs/assets/software-catalog/.$entity.svg.bkp @@ -0,0 +1,4 @@ + + + +
Envelop
Envelop
ApiVersion
version of the spec
ApiVersion...
Kind
entity type
Kind...
Spec
Describes the entity
Spec...
Metadata
Things that are not part of the spec
Metadata...
name
name
description
description
title
title
uid
uid
namespace
namespace
labels
labels
annotations
annotations
tags
tags
links
links
Entity
EntityText is not SVG - cannot display \ No newline at end of file diff --git a/docs/assets/software-catalog/entity.svg b/docs/assets/software-catalog/entity.svg index 32fb9d3f3f..ff637c407f 100644 --- a/docs/assets/software-catalog/entity.svg +++ b/docs/assets/software-catalog/entity.svg @@ -1,4 +1,4 @@ -
Envelop
Envelop
ApiVersion
version of the spec
ApiVersion...
Kind
entity type
Kind...
Spec
Describes the entity
Spec...
Metadata
Thins that are not part of the spec
Metadata...
name
name
description
description
title
title
uid
uid
namespace
namespace
labels
labels
annotations
annotations
tags
tags
links
links
Entity
EntityText is not SVG - cannot display \ No newline at end of file +
Envelop
Envelop
ApiVersion
version of the spec
ApiVersion...
Kind
entity type
Kind...
Spec
Describes the entity
Spec...
Metadata
Things that are not part of the spec
Metadata...
name
name
description
description
title
title
uid
uid
namespace
namespace
labels
labels
annotations
annotations
tags
tags
links
links
Entity
EntityText is not SVG - cannot display \ No newline at end of file diff --git a/docs/features/software-catalog/user-guide.md b/docs/features/software-catalog/user-guide.md index 75870bdb81..e86ddd43b2 100644 --- a/docs/features/software-catalog/user-guide.md +++ b/docs/features/software-catalog/user-guide.md @@ -54,8 +54,8 @@ The recommended approach would be to represent information in catalog-info files **Systems** - Jira installation -- Pageduty -- Physical resources: This is probably more useful for longer-lived ones (eg, servers). +- Pagerduty +- Physical resources: This is probably more useful for longer-lived ones (For example servers). **Ownership - users - groups by** From 744ace24f0df0fad22e049ccc1aaf458305abc18 Mon Sep 17 00:00:00 2001 From: Waldir Montoya <35240971+waldirmontoya25@users.noreply.github.com> Date: Thu, 30 Mar 2023 17:21:58 -0500 Subject: [PATCH 4/9] Update docs/features/software-catalog/user-guide.md Co-authored-by: Johan Haals Signed-off-by: Waldir Montoya <35240971+waldirmontoya25@users.noreply.github.com> --- docs/features/software-catalog/user-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-catalog/user-guide.md b/docs/features/software-catalog/user-guide.md index e86ddd43b2..105c9b120e 100644 --- a/docs/features/software-catalog/user-guide.md +++ b/docs/features/software-catalog/user-guide.md @@ -4,7 +4,7 @@ The Software Catalog in Backstage is intended to capture entities relevant to humans and have a clear mental model around them rather than an exhaustive inventory of all possible things. The focus is on attaching functionality and visual views centered around these entities. Determining the "edge" where the catalog ends and the external world begins is crucial to ensure that the catalog's scope is appropriate. The Backstage software catalog is a centralized hub for organizing and discovering software components and services. However, there may not be better tools for keeping track of the dynamic relationships between these components and services in real-time. Its primary objective is to offer a high-level overview of concepts rather than runtime aspects and to provide a user-friendly interface. To integrate data from external sources, it is recommended to attach tooling to the nodes in the graph using annotations. A front-end plugin can also be developed to showcase deployment information and other real-time data. -It is worth noting that the Backstage database should not be considered the ultimate source of truth. Instead, it is advisable to use the Backstage Catalog as a caching mechanism that utilizes a REST API to convey information to the catalog UI and other Backstage plugins. Adopting a GitOps approach is recommended to modify YAML files in Backstage, treating YAML files in repositories as the primary source of truth and using Scaffolder to make changes via the UI and generate a pull request in the repository with the updated changes. +It is worth noting that the Catalog should not be considered the ultimate source of truth. Instead, it is advisable to use the Backstage Catalog as a caching mechanism that utilizes a REST API to convey information to the catalog UI and other Backstage plugins. Adopting a GitOps approach is recommended to modify YAML files in Backstage, treating YAML files in repositories as the primary source of truth and using Scaffolder to make changes via the UI and generate a pull request in the repository with the updated changes. ### Descriptor Components used to build the Catalog Graph From ec17fe572a1a7eca6ab2f13bd7ed82115336857a Mon Sep 17 00:00:00 2001 From: Waldir Montoya <35240971+waldirmontoya25@users.noreply.github.com> Date: Thu, 30 Mar 2023 17:49:39 -0500 Subject: [PATCH 5/9] Correct H1 Heading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Waldir Montoya <35240971+waldirmontoya25@users.noreply.github.com> --- docs/features/software-catalog/user-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-catalog/user-guide.md b/docs/features/software-catalog/user-guide.md index 105c9b120e..3d920de482 100644 --- a/docs/features/software-catalog/user-guide.md +++ b/docs/features/software-catalog/user-guide.md @@ -1,4 +1,4 @@ -#Architecting your Catalog +# Architecting your Catalog ## Overview From 30831e48915ad85f8c034ef96e0a357f93955c88 Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Thu, 30 Mar 2023 19:06:13 -0500 Subject: [PATCH 6/9] Fix wording, image format and added links back to docs Signed-off-by: Waldir Montoya --- docs/assets/software-catalog/.$entity.svg.bkp | 4 -- .../{entity.svg => entity.drawio.svg} | 0 docs/features/software-catalog/user-guide.md | 37 +++++++++---------- 3 files changed, 18 insertions(+), 23 deletions(-) delete mode 100644 docs/assets/software-catalog/.$entity.svg.bkp rename docs/assets/software-catalog/{entity.svg => entity.drawio.svg} (100%) diff --git a/docs/assets/software-catalog/.$entity.svg.bkp b/docs/assets/software-catalog/.$entity.svg.bkp deleted file mode 100644 index a7b6fb1d7e..0000000000 --- a/docs/assets/software-catalog/.$entity.svg.bkp +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Envelop
Envelop
ApiVersion
version of the spec
ApiVersion...
Kind
entity type
Kind...
Spec
Describes the entity
Spec...
Metadata
Things that are not part of the spec
Metadata...
name
name
description
description
title
title
uid
uid
namespace
namespace
labels
labels
annotations
annotations
tags
tags
links
links
Entity
EntityText is not SVG - cannot display \ No newline at end of file diff --git a/docs/assets/software-catalog/entity.svg b/docs/assets/software-catalog/entity.drawio.svg similarity index 100% rename from docs/assets/software-catalog/entity.svg rename to docs/assets/software-catalog/entity.drawio.svg diff --git a/docs/features/software-catalog/user-guide.md b/docs/features/software-catalog/user-guide.md index 3d920de482..69fc75027c 100644 --- a/docs/features/software-catalog/user-guide.md +++ b/docs/features/software-catalog/user-guide.md @@ -1,32 +1,30 @@ -# Architecting your Catalog +#Architecting your Catalog ## Overview -The Software Catalog in Backstage is intended to capture entities relevant to humans and have a clear mental model around them rather than an exhaustive inventory of all possible things. The focus is on attaching functionality and visual views centered around these entities. Determining the "edge" where the catalog ends and the external world begins is crucial to ensure that the catalog's scope is appropriate. -The Backstage software catalog is a centralized hub for organizing and discovering software components and services. However, there may not be better tools for keeping track of the dynamic relationships between these components and services in real-time. Its primary objective is to offer a high-level overview of concepts rather than runtime aspects and to provide a user-friendly interface. To integrate data from external sources, it is recommended to attach tooling to the nodes in the graph using annotations. A front-end plugin can also be developed to showcase deployment information and other real-time data. -It is worth noting that the Catalog should not be considered the ultimate source of truth. Instead, it is advisable to use the Backstage Catalog as a caching mechanism that utilizes a REST API to convey information to the catalog UI and other Backstage plugins. Adopting a GitOps approach is recommended to modify YAML files in Backstage, treating YAML files in repositories as the primary source of truth and using Scaffolder to make changes via the UI and generate a pull request in the repository with the updated changes. +The Software Catalog in Backstage is intended to capture human mental models using entities and their relationships rather than an exhaustive inventory of all possible things. The focus is on attaching functionality and views centered around these entities. Determining the "edge" where the catalog ends and the external world begins is crucial to ensure that the catalog's scope is appropriate. +The Backstage software catalog serves as a centralized hub for organizing and discovering software components and services. While it excels at providing a high-level overview of these concepts, it may not be the ideal solution for tracking dynamic relationships between components and services in real-time. You can achieve real time views by attaching appropriate tooling to the nodes in the graph through [annotations](https://backstage.io/docs/features/software-catalog/well-known-annotations) and developing custom front-end plugins that display deployment information and other real-time data. +It is worth noting that the Backstage database should not be considered the ultimate source of truth. Instead, it is advisable to use the Backstage Catalog as a caching mechanism that utilizes a REST API to convey information to the catalog UI and other Backstage plugins. Adopting a GitOps approach is recommended to modify YAML files in Backstage, treating YAML files in repositories as the primary source of truth and using Scaffolder to make changes via the UI and generate a pull request in the repository with the updated changes. ### Descriptor Components used to build the Catalog Graph -**Entities:** An entity refers to a node in the graph that represents a distinct object, concept, or thing. Nodes are the fundamental building blocks of a graph database and are used to represent entities and their properties. +[**Entities:**](https://backstage.io/docs/features/software-catalog/system-model) An entity refers to a node in the graph that represents a distinct object, concept, or thing. Nodes are the fundamental building blocks of a graph database and are used to represent entities and their properties. -![](../../assets/software-catalog/entity.svg) +![](../../assets/software-catalog/entity.drawio.svg) -**Kinds:** These are broad categories used to group related entities. Kinds are used to provide a high-level categorization of entities, such as "service", "database", or "team". Kinds are often used to provide a way to filter entities in the catalog and to provide a high-level overview of the types of entities that are being managed. +[**Kinds:**](https://backstage.io/docs/features/software-catalog/descriptor-format#contents) These are broad categories used to group related entities. Kinds are used to provide a high-level categorization of entities, such as "service", "database", or "team". Kinds are often used to provide a way to filter entities in the catalog and to provide a high-level overview of the types of entities that are being managed. -**Relations:** These are links between different entities in the catalog. Relations express the relationships between different entities, such as dependencies or ownership. Adopters can use relations to help users navigate the catalog and understand the relationships between different entities. +[**Relations:**](https://backstage.io/docs/features/software-catalog/descriptor-format#common-to-all-kinds-relations) These are links between different entities in the catalog. Relations express the relationships between different entities, such as dependencies or ownership. Adopters can use relations to help users navigate the catalog and understand the relationships between different entities. -**Spec:** A specification or "spec" is a schema that outlines the data structure of an entity in the Backstage catalog. It defines the properties, relationships, data types, and constraints for an entity, ensuring consistency and accuracy of data while allowing for easy sharing and consumption of data across components and plugins. Specs are useful when creating or extending entities and can help make data more reusable and interoperable. The spec section is fully customizable, and users can create their own components and plugins to render the information. +[**Spec:**](https://backstage.io/docs/features/software-catalog/descriptor-format#spec-varies) A specification or "spec" is a schema that outlines the data structure of an entity in the Backstage catalog. It defines the properties, relationships, data types, and constraints for an entity, ensuring consistency and accuracy of data while allowing for easy sharing and consumption of data across components and plugins. Specs are useful when creating or extending entities and can help make data more reusable and interoperable. The spec section is fully customizable, and users can create their own components and plugins to render the information. -**Types:** These are more specific categories used to classify entities within a given Kind. Types provide a more granular categorization of entities, such as "frontend-service" or "backend-service.". Types are often used to provide additional context and information about an entity and to help users understand the role and function of the entity within the broader system. +[**Types:**](https://backstage.io/docs/features/software-catalog/system-model#type) These are more specific categories used to classify entities within a given Kind. Types provide a more granular categorization of entities, such as "frontend-service" or "backend-service.". Types are often used to provide additional context and information about an entity and to help users understand the role and function of the entity within the broader system. -**Annotations:** These key-value pairs can be attached to an entity in the catalog. They are typically used to add additional information or metadata to an entity. Annotations are often used to provide information that is used by automated tools or scripts and to provide further context to humans working with the entity or refer plugins to the external world. - -**Statuses:** These indicators represent an entity's current state. They are typically used to show whether an entity is healthy or not, whether it is up-to-date or out-of-date, or whether it is passing or failing various checks or tests. +[**Annotations:**](https://backstage.io/docs/features/software-catalog/well-known-annotations) These key-value pairs can be attached to an entity in the catalog. They are typically used to add additional information or metadata to an entity. Annotations are often used to provide information that is used by automated tools or scripts and to provide further context to humans working with the entity or refer plugins to the external world. ## Use cases out of the box -The catalog builds a graph using descriptors as nodes and relations as edges. Out of the box you get the following use cases: +The catalog builds a graph using [descriptors](https://backstage.io/docs/features/software-catalog/descriptor-format) as nodes and [relations](https://backstage.io/docs/features/software-catalog/descriptor-format#common-to-all-kinds-relations) as edges. Out of the box you get the following use cases: - Ownership tracking - Inventory @@ -42,7 +40,7 @@ The recommended approach would be to represent information in catalog-info files ### Well-known trackable assets -**Software Components** +**Components** - Services - Websites @@ -50,12 +48,13 @@ The recommended approach would be to represent information in catalog-info files - Data Pipelines - Machine Learning Models - Third-party software components: It is recommended to have a separate repo for all 3d party catalog-info files. - -**Systems** - - Jira installation - Pagerduty + +**Resources** + - Physical resources: This is probably more useful for longer-lived ones (For example servers). +- Cloud Infrastructure services **Ownership - users - groups by** @@ -84,7 +83,7 @@ The recommended approach would be to represent information in catalog-info files APIs Could list networked services or libraries and it’s particularly useful to identify APIs that form boundaries between systems. There are some considerations to keep in mind: -**API versions:** It’s not recommended to have multiple entity instances (e.g., metadata.name: my-api-v1 and metadata.name: my-api-v2). +**API versions:** Major API versions can be treated as distinct APIs, and it is possible to create separate entity instances for each (e.g., metadata.name: my-api-v1 and metadata.name: my-api-v2). However, this approach is not recommended for minor or patch-level variations **Detail:** It’s not recommended going too granular because the catalog in its current form won't perhaps be a great platform to express it. From 10156830b9ff7245e365130245b2bfb132522aef Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Tue, 18 Apr 2023 09:29:33 -0500 Subject: [PATCH 7/9] Add the document to the microsite Signed-off-by: Waldir Montoya --- .../{user-guide.md => architecting-the-catalog.md} | 8 ++++---- microsite/sidebars.json | 3 ++- 2 files changed, 6 insertions(+), 5 deletions(-) rename docs/features/software-catalog/{user-guide.md => architecting-the-catalog.md} (87%) diff --git a/docs/features/software-catalog/user-guide.md b/docs/features/software-catalog/architecting-the-catalog.md similarity index 87% rename from docs/features/software-catalog/user-guide.md rename to docs/features/software-catalog/architecting-the-catalog.md index 69fc75027c..922dcad3ad 100644 --- a/docs/features/software-catalog/user-guide.md +++ b/docs/features/software-catalog/architecting-the-catalog.md @@ -1,10 +1,10 @@ -#Architecting your Catalog +# Architecting your Catalog ## Overview The Software Catalog in Backstage is intended to capture human mental models using entities and their relationships rather than an exhaustive inventory of all possible things. The focus is on attaching functionality and views centered around these entities. Determining the "edge" where the catalog ends and the external world begins is crucial to ensure that the catalog's scope is appropriate. -The Backstage software catalog serves as a centralized hub for organizing and discovering software components and services. While it excels at providing a high-level overview of these concepts, it may not be the ideal solution for tracking dynamic relationships between components and services in real-time. You can achieve real time views by attaching appropriate tooling to the nodes in the graph through [annotations](https://backstage.io/docs/features/software-catalog/well-known-annotations) and developing custom front-end plugins that display deployment information and other real-time data. -It is worth noting that the Backstage database should not be considered the ultimate source of truth. Instead, it is advisable to use the Backstage Catalog as a caching mechanism that utilizes a REST API to convey information to the catalog UI and other Backstage plugins. Adopting a GitOps approach is recommended to modify YAML files in Backstage, treating YAML files in repositories as the primary source of truth and using Scaffolder to make changes via the UI and generate a pull request in the repository with the updated changes. +The Backstage software catalog serves as a centralized hub for organizing and discovering software components and services. While it excels at providing a high-level overview of these concepts, it may not be the ideal solution for tracking dynamic relationships between components and services in real-time. You can achieve real time views by attaching appropriate tooling to the nodes in the graph through [annotations](https://backstage.io/docs/features/software-catalog/well-known-annotations) and developing custom front-end [plugins](http://localhost:3000/docs/plugins/) that display deployment information and other real-time data. +It is worth noting that the Backstage Software Catalog should not be considered the ultimate source of truth, instead, it is advisable to use the Backstage Catalog as a caching mechanism that utilizes a REST API to convey information to the catalog UI and other Backstage plugins. Adopting a GitOps approach is recommended to modify YAML files in Backstage, treating YAML files in repositories as the primary source of truth and using Scaffolder to make changes via the UI and generate a pull request in the repository with the updated changes. ### Descriptor Components used to build the Catalog Graph @@ -70,7 +70,7 @@ The recommended approach would be to represent information in catalog-info files **Ownership based on teams:** The concept of ownership in the system is team-centric; hence, the "owner" field must reference the LDAP name of a squad according to a prescribed set of regulations. While there may be instances where the ownership is attributed to an individual, such deviations might create challenges. In such cases, the user could receive a notification through the web interface, highlighting that this departure is an exception and needs rectification. To ensure adherence to this system, every entity in the model should have a designated owner, preferably a valid team within the LDAP hierarchy. -**Ownership of features:** To track the ownership of specific features within your products and their interrelationships, two options are available: introducing a new component type, such as "feature," or creating a new Kind altogether. Nonetheless, it is advisable to choose the former approach and introduce a new type, like "feature," is advisable as it is less complicated and poses a lower risk. +**Ownership of features:** To track the ownership of specific features within your products and their interrelationships, two options are available: introducing a new component [type](https://backstage.io/docs/features/software-catalog/system-model/#type), such as "feature," or creating a new [Kind](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) altogether. Nonetheless, it is advisable to choose the former approach and introduce a new type, like "feature," is advisable as it is less complicated and poses a lower risk. **LDAP doesn’t reflect the organization structure:** If Workday or a similar system serves as the source of truth, and LDAP is utilized for user attributes, it is advisable to develop a layer on top of various systems to establish a unified API that the entire organization can query, rather than only Backstage. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 1515c483b9..c2d18925eb 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -80,7 +80,8 @@ "features/software-catalog/extending-the-model", "features/software-catalog/external-integrations", "features/software-catalog/catalog-customization", - "features/software-catalog/software-catalog-api" + "features/software-catalog/software-catalog-api", + "features/software-catalog/architecting-the-catalog" ] }, { From 5b13710ea21480b5adb5571731dae5905dcc270c Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Thu, 20 Apr 2023 14:12:36 -0500 Subject: [PATCH 8/9] Correct entity diagram envelope word Signed-off-by: Waldir Montoya --- .gitignore | 6 +++++- docs/assets/software-catalog/entity.drawio.svg | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index f3c687d49c..c0bf195947 100644 --- a/.gitignore +++ b/.gitignore @@ -155,4 +155,8 @@ tsconfig.tmp.json # Lighthouse CI Reports **/.lighthouseci/* -!**/.lighthouseci/scripts \ No newline at end of file +!**/.lighthouseci/scripts + +# VS Code backing up svg files +*svg.bkp +*svg.dtmp \ No newline at end of file diff --git a/docs/assets/software-catalog/entity.drawio.svg b/docs/assets/software-catalog/entity.drawio.svg index ff637c407f..557d037ecd 100644 --- a/docs/assets/software-catalog/entity.drawio.svg +++ b/docs/assets/software-catalog/entity.drawio.svg @@ -1,4 +1,4 @@ -
Envelop
Envelop
ApiVersion
version of the spec
ApiVersion...
Kind
entity type
Kind...
Spec
Describes the entity
Spec...
Metadata
Things that are not part of the spec
Metadata...
name
name
description
description
title
title
uid
uid
namespace
namespace
labels
labels
annotations
annotations
tags
tags
links
links
Entity
EntityText is not SVG - cannot display \ No newline at end of file +
Envelope
Envelope
ApiVersion
version of the spec
ApiVersion...
Kind
entity type
Kind...
Spec
Describes the entity
Spec...
Metadata
Things that are not part of the spec
Metadata...
name
name
description
description
title
title
uid
uid
namespace
namespace
labels
labels
annotations
annotations
tags
tags
links
links
Entity
EntityText is not SVG - cannot display \ No newline at end of file From 66ea69cb02ddba3f3f6a9ee941d37bf0a6125fb7 Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Tue, 9 May 2023 12:17:33 -0500 Subject: [PATCH 9/9] Changing the title for the speller checker Signed-off-by: Waldir Montoya --- ...rchitecting-the-catalog.md => creating-the-catalog-graph.md} | 2 +- microsite/sidebars.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/features/software-catalog/{architecting-the-catalog.md => creating-the-catalog-graph.md} (99%) diff --git a/docs/features/software-catalog/architecting-the-catalog.md b/docs/features/software-catalog/creating-the-catalog-graph.md similarity index 99% rename from docs/features/software-catalog/architecting-the-catalog.md rename to docs/features/software-catalog/creating-the-catalog-graph.md index 922dcad3ad..8b0f21a52c 100644 --- a/docs/features/software-catalog/architecting-the-catalog.md +++ b/docs/features/software-catalog/creating-the-catalog-graph.md @@ -1,4 +1,4 @@ -# Architecting your Catalog +# Creating the Catalog Graph ## Overview diff --git a/microsite/sidebars.json b/microsite/sidebars.json index c2d18925eb..ea34604e26 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -81,7 +81,7 @@ "features/software-catalog/external-integrations", "features/software-catalog/catalog-customization", "features/software-catalog/software-catalog-api", - "features/software-catalog/architecting-the-catalog" + "features/software-catalog/creating-the-catalog-graph" ] }, {