Locations

Summary

A location is a marker that references other places to look for catalog data. These are often used to register multiple entities with the catalog from a single discovery location by performing redirection to adjacent entity descriptors.

Definition

Backstage Docs

See the backstage docs for a full description of the Location entity definition.

As with all other entities, a location consists of the envelope types, apiVersion and kind, as well as generic metadata and a specific spec.

apiVersion [Required]

The apiVersion is the version of specification format for that particular entity that the specification is made against. The version is used for being able to evolve the format and to distinguish them from other types of object that share the same type of structure - e.g. Kubernetes object manifests.

At present all entity descriptors should be given an apiVersion of backstage.io/v1alpha1. This will change as backstage develops or if we choose to add custom entity kinds to the portal.

kind [Required]

The kind is the high level entity type being described. For an entity location this must be Location, e.g. kind: Location.

Other available kinds are enumerated in the entity types reference.

metadata [Required]

A structure that contains metadata about the entity, i.e. things that aren't directly part of the entity specification itself. See the entity metadata reference for more details about this structure.

name [Required]

The name of the entity. This name is both meant for human eyes to recognize the entity, and for machines and other components to reference the entity, e.g. visits-tracking-service

Names must be unique per kind, at any point in time. This uniqueness constraint is case insensitive. Names may be reused at a later time, after an entity is deleted from the registry.

Names are required to follow a certain format. Entities that do not follow those rules will not be accepted for registration in the catalog. The required format is as follows:

• Strings of length at least 1, and at most 63
• Must consist of sequences of [a-z0-9A-Z] possibly separated by one of [-_.]

title [Optional]

A display name of the entity, to be presented in user interfaces instead of the name property above, when available.

This field is sometimes useful when the name is cumbersome or ends up being perceived as overly technical. The title generally does not have as stringent format requirements on it, so it may contain special characters and be more explanatory. Do keep it very short though, and avoid situations where a title can be confused with the name of another entity, or where two entities share a title.

Note that this is only for display purposes, and may be ignored by some parts of the code. Entity references still always make use of the name property for example, not the title.

description [Optional]

A human readable description of the entity, to be shown in the developer portal. Should be kept short and informative, suitable to give an overview of the entity's purpose at a glance. More detailed explanations and documentation should be placed elsewhere.

labels [Optional]

Labels are optional key/value pairs of that are attached to the entity, and their use is identical to Kubernetes object labels.

Their main purpose is for references to other entities, and for information that is in one way or another classifying for the current entity. They are often used as values in queries or filters.

Both the key and the value are strings, subject to the following restrictions.

Keys have an optional prefix followed by a slash, and then the name part which is required. The prefix, if present, must be a valid lowercase domain name, at most 253 characters in total. The name part must be sequences of [a-zA-Z0-9] separated by any of [-_.], at most 63 characters in total.

The backstage.io/ prefix is reserved for use by Backstage core components.

Values are strings that follow the same restrictions as name above.

annotations [Optional]

An object with arbitrary non-identifying metadata attached to the entity, identical in use to Kubernetes object annotations.

Their purpose is mainly, but not limited, to reference into external systems. This could for example be a reference to the git ref the entity was ingested from, to monitoring and logging systems, to PagerDuty schedules, etc. Users may add these to descriptor YAML files, but in addition to this automated systems may also add annotations, either during ingestion into the catalog, or at a later time.

Both the key and the value are strings, subject to the following restrictions.

Keys have an optional prefix followed by a slash, and then the name part which is required. The prefix must be a valid lowercase domain name if specified, at most 253 characters in total. The name part must be sequences of [a-zA-Z0-9] separated by any of [-_.], at most 63 characters in total.

The backstage.io/ prefix is reserved for use by Backstage core components.

Values can be of any length, but are limited to being strings.

tags [Optional]

A list of single-valued strings, for example to classify catalog entities in various ways. This is different to the labels in metadata, as labels are key-value pairs.

The values are user defined, for example the programming language used for the component, like java or go.

This field is optional, and currently has no special semantics.

Each tag must be sequences of [a-z0-9] separated by -, at most 63 characters in total.

links [Optional]

A list of external hyperlinks related to the entity. Links can provide additional contextual information that may be located outside of the developer portal itself. For example, an admin dashboard or external CMS page.

Users may add links to descriptor YAML files to provide additional reference information to external content & resources. Links are not intended to drive any additional functionality within Backstage, which is best left to annotations and labels. It is recommended to use links only when an equivalent well-known annotation does not cover a similar use case.

Fields of a link are:

url [Required]

A url in a standard uri format, e.g. url: https://example.com/some/page

title [Optioanl]

A user friendly display name for the link, e.g. title: Example Website

icon [Optional]

A key representing a visual icon to be displayed in the UI, e.g. icon: docs

The icon field value is meant to be a semantic key that will map to a specific icon that may be provided by an icon library (e.g. material-ui icons). These keys should be a sequence of [a-z0-9A-Z], possibly separated by one of [-_.]. The default backstage icon-component mappings are used, see the app-defaults for details. A generic fallback icon would be provided if a mapping cannot be resolved.

spec [Required]

The actual specification data that describes the entity.

type [Optional]

The single location type, that's common to the targets specified in the spec. Typically, this should be left empty such that the location type of the target is inherited from the location type of the location entity which defines it (i.e. your defined location). Other options include url - which instructs the catalog to retrieve the descriptor from the URL; or file - which instructs the catalog to retrieve the descriptor from a local file.

targets [Optional]

A list of targets as strings. They can all be either absolute paths/URLs (depending on the type), or relative paths which are resolved relative to the location of this Location entity itself. e.g.:

targets:
  - ./frontend/component-info.yaml
  - ./backend/component-info.yaml
  - ./backend/api-info.yaml

presence [Optional]

Describes whether the target of a location is required to exist or not. It defaults to required if not specified, can also be optional.