Systems¶
Summary¶
A system is a collection of resources and components. The system may expose or consume one or several APIs. It is viewed as abstraction level that provides potential consumers insights into exposed features without needing a too detailed view into the details of all components. This also gives the owning team the possibility to decide about published artifacts and APIs.
Definition¶
Backstage Docs
See the backstage docs for a full description of the System entity definition.
As with all other entities, a system 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 system this must be System, e.g. kind: System.
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.
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.
domain [Optional]¶
An entity reference to the Domain that the system belongs to, e.g. developer-tooling. There is no requirement for this Domain to be created within the same location; Existing Domains can be listed in the catalog by filtering by Kind of Domain.