Components

Summary

A Component describes a software component. It is typically intimately linked to the source code that constitutes the component, and should be what a developer may regard a "unit of software", usually with a distinct deployable or linkable artifact.

Definition

Backstage Docs

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

As with all other entities, a component 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 a software component this must be Component, e.g. kind: Component.

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 [Required]

The type of Component as a string, e.g. type: service.

Whilst the type of a Component may be any string, it is strongly recommended that you use one of the common values. Futher to this, tools including Backstage itself may read this field and behave differently depending on its value. For example, a website type component may present tooling in the Backstage interface that is specific to just websites. Thus we recommend that when specifying a component one of the following is used in this field:

• library - a software library
• service - a backend service, typically exposing an API
• user-interface - a local user interface
• website - a web user interface

lifecycle [Required]

The lifecycle state of the Component as a string, e.g. lifecycle: production.

Whilst the spec.type of a Component or API may be any string, understanding is made easier by sticking to a small set of well-known and common values. Thus we recommend that when specifying an entity one of the following is used in this field:

• experimental - an experiment or early, non-production entity, signaling that users may not prefer to consume it over other more established entities, or that there are low or no reliability guarantees
• production - an established, owned, maintained entity
• deprecated - an entity that is at the end of its lifecycle, and may disappear at a later point in time

owner [Required]

An entity reference to the owner of the entity, e.g. owner: user:enu43627. Users and Groups are automatically populated, and can listed in the catalog by filtering by Kind of User or Group respectively.

The owner of an entity is the group or user that bears ultimate responsibility for the entity, and has the authority and capability to develop and maintain it. They will be the point of contact if something goes wrong, or if features are to be requested. The main purpose of this field is for display purposes in Backstage, so that people looking at catalog items can get an understanding of to whom this entity belongs. It is not to be used by automated processes to for example assign authorization in runtime systems. There may be others that also develop or otherwise touch the entity, but there will always be one ultimate owner.

system [Optional]

An entity reference to the System that the entity belongs to, e.g. developer-portal. There is no requirement for this System to be created within the same location; Existing Systems can be listed in the catalog by filtering by Kind of System.

subcomponentOf [Optional]

An entity reference to another Component of which this Component is part of, e.g. subComponentOf: developer-portal-frontend. There is no requirement for this Component to be created within the same location; Existing Components can be listed in the catalog by filtering by Kind of Component.

providesApis [Optional]

An array of entity references to the APIs that are provided by the Component, e.g. providesApis: [developer-portal-backend-rest]. There is no requirement for these APIs to be created within the same location; Existing APIs can be listed in the catalog by filtering by Kind of API.

consumesApis [Optional]

An array of entity references to the APIs that are consumed by the Component, e.g. consumesApis: [developer-portal-backend-rest]. There is no requirement for these APIs to be created within the same location; Existing APIs can be listed in the catalog by filtering by Kind of API.

dependsOn [Optional]

An array of entity references to the Components and Resources that this entity depends on, e.g. dependsOn: [component:developer-portal-backend]. There is no requirement for these entities to be created within the same location; Existing entities can be listed in the catalog.