[RFC] Entity Links

Status: Open for comments

This is a formal proposal for a discussion on discord

Need

It is common to have existing external information or references related to entities in the catalog. These could often be represented as hyperlinks to some external reference when no related well known annotation or plugin exists. Some examples of this might be.

• Deployed website, demo site, etc.
• Admin dashboard for a service/website
• External documentation, API references, storybooks, etc.
• External team README page
• Runtime dashboards, etc.
• Various SasS integrations
• … and the list goes on and on

Having the ability to attach this information to entities would open the world for providing a common Links card component on each entity page. These links could contain some basic context in order to indicate their semantic purpose (e.g. admin-dashboard, or api-docs, etc.)

Proposal

Provide a lightweight and quick way to extend an entity with an optional list of basic links to external information & references. This new field could be support some well-known links, org specific links, or specific entity instance links. The list of links could then be managed by entity owners or possibly automatically appended through catalog processors.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: petstore
  links: # optional
    - url: https://admin.petstore.com  # required
      rel: admin-dashboard # optional but recommended to provide semantic meaning
      label: Admin Dashboard # optional and could be inferred by rel if omitted
spec:
  type: website
  ...

It would also be nice to have the ability to associate icons to links. This could be done through the rel attribute or perhaps more appropriately an optional icon field (or both with rel as a fallback if provided). The icon value could be an enum value that maps to a icon library such as iconify.

metadata:
  links:
    - url: https://admin.petstore.com
      label: Admin Dashboard
      icon: dashboard-icon

It might be possible to have a short form string version that might be expanded to it’s constituent parts. However escaping might be a concern that makes this less feasible. For example:

metdata:
  links:
    - http://admin.petstore.com # just a url
    - url=http://admin.petstore.com,rel=admin-dashboard # a inline map
    - { url: 'http://admin.petstore.com' } # inline yaml object

Alternatives

Links could probably be modeled as annotations:

metdata:
  annotations:
    # Format: [links.backstage.io/${rel}]: [value]
    links.backstage.io/admin-dashboard: https://admin.petstore.com

However, since annotations are typically single values the ability to provide additional context of a label & icon, etc. could be harder to maintain.

Risks

The concept of links can overlap with the existing entity annotations and possibly tags. They also could be modeled by extended either of these existing concepts. Also the concept of links is quite subjective and could mean anything making it a bit abstract and difficult to define when you would use a link versus an annotation.

Forcing people to use annotations to model a simple external reference could mean they don’t attach this useful information as it requires additional setup for a specific case. On the flip side having a quick to use links field could be used as a dumping ground and therefore deter people from modelling proper annotations when appropriate. However, these potential points of confusion can be reduced through guidance and documentation.

[andrewthauer]

Perhaps icon might be more appropriate since it really is the main use case. I never had the intention for these links to be filtered or selectively used as a subset based on the type. One could still resolve the title based on the icon key if desired, but this would potentially be a misuse of icon. So …

metadata:
  name: petstore
  links: # optional
    - url: https://admin.petstore.com  # required
      title: Admin Dashboard # optional
      icon: dashboard # optional

Are we ok having the icon value as a key like string? The intention being any components displaying links would have the option of using this icon key to map to an appropriate react icon. This approach would provide the most flexibility but would put more work on the maintainers of backstage. Although, I suspect it could be extended to make this easier and more automatic.

[Rugvip]

@andrewthauer Yep! As long as we also include at least a rudimentary icon system in the initial PR, perhaps with just a couple of hardcoded icons, but with some clear IDs of how to expand and making them configurable.