docs(catalog): document the current set of well known annotations
This commit is contained in:
Fredrik Adelöw
@@ -235,6 +235,9 @@ The `backstage.io/` prefix is reserved for use by Backstage core components.
|
||||
|
||||
Values can be of any length, but are limited to being strings.
|
||||
|
||||
There is a list of [well-known annotations](well-known-annotations.md), but
|
||||
anybody is free to add more annotations as they see fit.
|
||||
|
||||
### `tags` [optional]
|
||||
|
||||
A list of single-valued strings, for example to classify catalog entities in
|
||||
@@ -290,7 +293,7 @@ Exactly equal to `backstage.io/v1alpha1` and `Component`, respectively.
|
||||
|
||||
The type of component as a string, e.g. `website`. This field is required.
|
||||
|
||||
The software catalog accepts any type value, but an organisation should take
|
||||
The software catalog accepts any type value, but an organization should take
|
||||
great care to establish a proper taxonomy for these. 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
|
||||
@@ -304,9 +307,9 @@ The current set of well-known and common values for this field is:
|
||||
|
||||
### `spec.lifecycle` [required]
|
||||
|
||||
The lifecyle state of the component, e.g. `production`. This field is required.
|
||||
The lifecycle state of the component, e.g. `production`. This field is required.
|
||||
|
||||
The software catalog accepts any lifecycle value, but an organisation should
|
||||
The software catalog accepts any lifecycle value, but an organization should
|
||||
take great care to establish a proper taxonomy for these.
|
||||
|
||||
The current set of well-known and common values for this field is:
|
||||
@@ -418,7 +421,7 @@ potentially search and group templates by these tags.
|
||||
The type of component as a string, e.g. `website`. This field is optional but
|
||||
recommended.
|
||||
|
||||
The software catalog accepts any type value, but an organisation should take
|
||||
The software catalog accepts any type value, but an organization should take
|
||||
great care to establish a proper taxonomy for these. 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
|
||||
@@ -508,7 +511,7 @@ Exactly equal to `backstage.io/v1alpha1` and `API`, respectively.
|
||||
The type of the API definition as a string, e.g. `openapi`. This field is
|
||||
required.
|
||||
|
||||
The software catalog accepts any type value, but an organisation should take
|
||||
The software catalog accepts any type value, but an organization should take
|
||||
great care to establish a proper taxonomy for these. Tools including Backstage
|
||||
itself may read this field and behave differently depending on its value. For
|
||||
example, an OpenAPI type API may be displayed using an OpenAPI viewer tooling in
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
id: well-known-annotations
|
||||
title: Well-known Annotations on Catalog Entities
|
||||
sidebar_label: Well-known Annotations
|
||||
---
|
||||
|
||||
This section lists a number of well known
|
||||
[annotations](descriptor-format.md#annotations-optional), that have defined
|
||||
semantics. They can be attached to catalog entities and consumed by plugins as
|
||||
needed.
|
||||
|
||||
## Annotations
|
||||
|
||||
This is a (non-exhaustive) list of annotations that are known to be in active
|
||||
use.
|
||||
|
||||
### backstage.io/managed-by-location
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/managed-by-location: github:http://github.com/spotify/backstage/catalog-info.yaml
|
||||
```
|
||||
|
||||
The value of this annotation is a so called location reference string, that
|
||||
points to the source from which the entity was originally fetched. This
|
||||
annotation is added automatically by the catalog as it fetches the data from a
|
||||
registered location, and is not meant to normally be written by humans. The
|
||||
annotation may point to any type of generic location that the catalog supports,
|
||||
so it cannot be relied on to always be specifically of type `github`, nor that
|
||||
it even represents a single file. Note also that a single location can be the
|
||||
source of many entities, so it represents a many-to-one relationship.
|
||||
|
||||
The format of the value is `<type>:<target>`. Note that the target may also
|
||||
contain colons, so it is not advisable to naively split the value on `:` and
|
||||
expecting a two-item array out of it. The format of the target part is
|
||||
type-dependent and could conceivably even be an empty string, but the separator
|
||||
colon is always present.
|
||||
|
||||
### backstage.io/techdocs-ref
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git
|
||||
```
|
||||
|
||||
The value of this annotation is a location reference string (see above). If this
|
||||
annotation is specified, it is expected to point to a repository that the
|
||||
TechDocs system can read and generate docs from.
|
||||
|
||||
### backstage.io/jenkins-github-folder
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/jenkins-github-folder: folder-name/job-name
|
||||
```
|
||||
|
||||
The value of this annotation is the path to a job on Jenkins, that builds this
|
||||
entity.
|
||||
|
||||
Specifying this annotation may enable Jenkins related features in Backstage for
|
||||
that entity.
|
||||
|
||||
### github.com/project-slug
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
github.com/project-slug: spotify/backstage
|
||||
```
|
||||
|
||||
The value of this annotation is the so-called slug that identifies a project on
|
||||
[GitHub](https://github.com) that is related to this entity. It is on the format
|
||||
`<organization>/<project>`, and is the same as can be seen in the URL location
|
||||
bar of the browser when viewing that project.
|
||||
|
||||
Specifying this annotation will enable GitHub related features in Backstage for
|
||||
that entity.
|
||||
|
||||
### sentry.io/project-slug
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
sentry.io/project-slug: pump-station
|
||||
```
|
||||
|
||||
The value of this annotation is the so-called slug (or alternatively, the ID) of
|
||||
a [Sentry](https://sentry.io) project within your organization. The organization
|
||||
slug is currently not configurable on a per-entity basis, but is assumed to be
|
||||
the same for all entities in the catalog.
|
||||
|
||||
Specifying this annotation may enable Sentry related features in Backstage for
|
||||
that entity.
|
||||
|
||||
## Deprecated Annotations
|
||||
|
||||
The following annotations are deprecated, and only listed here to aid in
|
||||
migrating away from them.
|
||||
|
||||
### backstage.io/github-actions-id
|
||||
|
||||
This annotation was used for a while to enable the GitHub Actions feature. This
|
||||
is now instead using the [github.com/project-slug](#github-com-project-slug)
|
||||
annotation, with the same value format.
|
||||
|
||||
## Links
|
||||
|
||||
- [Descriptor Format: annotations](descriptor-format.md#annotations-optional)
|
||||
Reference in New Issue
Block a user