docs: catalog - extending the model, and relations (#3291)
* docs: catalog - extending the model, and relations * Address comments
This commit is contained in:
Fredrik Adelöw
@@ -22,11 +22,15 @@ we recommend that you name them `catalog-info.yaml`.
|
||||
- [Overall Shape Of An Entity](#overall-shape-of-an-entity)
|
||||
- [Common to All Kinds: The Envelope](#common-to-all-kinds-the-envelope)
|
||||
- [Common to All Kinds: The Metadata](#common-to-all-kinds-the-metadata)
|
||||
- [Common to All Kinds: Relations](#common-to-all-kinds-relations)
|
||||
- [Kind: Component](#kind-component)
|
||||
- [Kind: Template](#kind-template)
|
||||
- [Kind: API](#kind-api)
|
||||
- [Kind: Group](#kind-group)
|
||||
- [Kind: User](#kind-user)
|
||||
- [Kind: Resource](#kind-resource)
|
||||
- [Kind: System](#kind-system)
|
||||
- [Kind: Domain](#kind-domain)
|
||||
|
||||
## Overall Shape Of An Entity
|
||||
|
||||
@@ -259,6 +263,61 @@ 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.
|
||||
|
||||
## Common to All Kinds: Relations
|
||||
|
||||
The `relations` root field is a read-only list of relations, between the current
|
||||
entity and other entities, described in the
|
||||
[well-known relations section](well-known-relations.md). Relations are commonly
|
||||
two-way, so that there's a pair of relation types each describing one direction
|
||||
of the relation.
|
||||
|
||||
A relation as part of a single entity that's read out of the API may look as
|
||||
follows.
|
||||
|
||||
```js
|
||||
{
|
||||
// ...
|
||||
"relations": [
|
||||
{
|
||||
"target": {
|
||||
"kind": "group",
|
||||
"namespace": "default",
|
||||
"name": "dev.infra"
|
||||
},
|
||||
"type": "ownedBy"
|
||||
}
|
||||
],
|
||||
"spec": {
|
||||
"owner": "dev.infra",
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The fields of a relation are:
|
||||
|
||||
| Field | Type | Description |
|
||||
| ---------- | ------ | -------------------------------------------------------------------------------- |
|
||||
| `target` | Object | A complete [compound reference](references.md) to the other end of the relation. |
|
||||
| `type` | String | The type of relation FROM a source entity TO the target entity. |
|
||||
| `metadata` | Object | Reserved for future use. |
|
||||
|
||||
Entity descriptor YAML files are not supposed to contain this field. Instead,
|
||||
catalog processors analyze the entity descriptor data and its surroundings, and
|
||||
deduce relations that are then attached onto the entity as read from the
|
||||
catalog.
|
||||
|
||||
Where relations are produced, they are to be considered the authoritative source
|
||||
for that piece of data. In the example above, a plugin would do better to
|
||||
consume the relation rather than `spec.owner` for deducing the owner of the
|
||||
entity, because it may even be the case that the owner isn't taken from the YAML
|
||||
at all - it could be taken from a CODEOWNERS file nearby instead for example.
|
||||
Also, the `spec.owner` is on a shortened form and may have semantics associated
|
||||
with it (such as the default kind being `Group` if not specified).
|
||||
|
||||
See the [well-known relations section](well-known-relations.md) for a list of
|
||||
well-known / common relations and their semantics.
|
||||
|
||||
## Kind: Component
|
||||
|
||||
Describes the following entity kind:
|
||||
@@ -740,3 +799,15 @@ with the default kind `Group` and the default namespace equal to the same
|
||||
namespace as the user. Only `Group` entities may be referenced. Most commonly,
|
||||
these entries point to groups in the same namespace, so in those cases it is
|
||||
sufficient to enter only the `metadata.name` field of those groups.
|
||||
|
||||
## Kind: Resource
|
||||
|
||||
This kind is not yet defined, but is reserved [for future use](system-model.md).
|
||||
|
||||
## Kind: System
|
||||
|
||||
This kind is not yet defined, but is reserved [for future use](system-model.md).
|
||||
|
||||
## Kind: Domain
|
||||
|
||||
This kind is not yet defined, but is reserved [for future use](system-model.md).
|
||||
|
||||
@@ -4,6 +4,36 @@ title: Extending the model
|
||||
description: Documentation on Extending the model
|
||||
---
|
||||
|
||||
The Backstage catalog [entity data model](descriptor-format.md) is based on the
|
||||
[Kubernetes objects format](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/),
|
||||
and borrows a lot of its semantics as well. This page describes those semantics
|
||||
at a higher level and how to extend them to fit your organization.
|
||||
|
||||
Backstage comes with a number of catalog concepts out of the box:
|
||||
|
||||
- There are a number of builtin versioned _kinds_, such as `Component`, `User`
|
||||
etc. These encapsulate the high level concept of an entity, and define the
|
||||
schema for its entity definition data.
|
||||
- An entity has both a _metadata_ object and a _spec_ object at the root.
|
||||
- Each kind may or may not have a _type_. For example, there are several well
|
||||
known types of component, such as `service` and `website`. These clarify the
|
||||
more detailed nature of the entity, and may affect what features are exposed
|
||||
in the interface.
|
||||
- Entities may have a number of _[annotations](well-known-annotations.md)_ on
|
||||
them. These can be added either by humans into the descriptor files, or added
|
||||
by automated processes when the entity is ingested into the catalog.
|
||||
- Entities may have a number of _labels_ on them.
|
||||
- Entities may have a number of _relations_, expressing how they relate to each
|
||||
other in different ways.
|
||||
|
||||
We'll list different possibilities for extending this below.
|
||||
|
||||
## Adding a New Kind
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
## Adding a New Type of an Existing Kind
|
||||
|
||||
Backstage natively supports tracking of the following component
|
||||
[`type`](descriptor-format.md)'s:
|
||||
|
||||
@@ -20,13 +50,6 @@ track in Backstage, it is possible to add your own software types that fit your
|
||||
organization's data model. Inside Spotify our model has grown significantly over
|
||||
the years, and now includes ML models, Apps, data pipelines and many more.
|
||||
|
||||
## Adding a new type
|
||||
|
||||
TODO: Describe what changes are needed to add a new type that shows up in the
|
||||
catalog.
|
||||
|
||||
## The Other type
|
||||
|
||||
It might be tempting to put software that doesn't fit into any of the existing
|
||||
types into Other. There are a few reasons why we advise against this; firstly,
|
||||
we have found that it is preferred to match the conceptual model that your
|
||||
@@ -39,3 +62,29 @@ For example, the
|
||||
[Lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse)
|
||||
only makes sense for Websites. The more specific you can be in how you model
|
||||
your software, the easier it is to provide plugins that are contextual.
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
## Changing the Validation Rules for Core Entity Fields
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
## Adding New Fields to the Metadata Object
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
## Adding New Fields to the Spec Object of an Existing Kind
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
## Adding a New Annotation
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
## Adding a New Label
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
## Adding a New Relation Type
|
||||
|
||||
> TODO: Fill in
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
id: well-known-annotations
|
||||
title: Well-known Annotations on Catalog Entities
|
||||
sidebar_label: Well-known Annotations
|
||||
description: Documentation on lists a number of well known Annotations, that
|
||||
description: Documentation that lists a number of well known Annotations, that
|
||||
have defined semantics. They can be attached to catalog entities and consumed
|
||||
by plugins as needed
|
||||
by plugins as needed.
|
||||
---
|
||||
|
||||
This section lists a number of well known
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
id: well-known-relations
|
||||
title: Well-known Relations between Catalog Entities
|
||||
sidebar_label: Well-known Relations
|
||||
description: Documentation that lists a number of well known Relations, that
|
||||
have defined semantics. They can be attached to catalog entities and consumed
|
||||
by plugins as needed.
|
||||
---
|
||||
|
||||
This section lists a number of well known
|
||||
[entity relation types](descriptor-format.md#common-to-all-kinds-relations),
|
||||
that have defined semantics. They can be attached to catalog entities and
|
||||
consumed by plugins as needed.
|
||||
|
||||
If you are looking to extend the set of relations, see
|
||||
[Extending the model](extending-the-model.md).
|
||||
|
||||
## Relations
|
||||
|
||||
This is a (non-exhaustive) list of relations that are known to be in active use.
|
||||
|
||||
Each relation has a _source_ (implicitly: the entity that holds the relation), a
|
||||
_target_ (the entity to which the source has a relation), and a _type_ that
|
||||
tells what relation the source has with the target. The relation is directional;
|
||||
there are commonly pairs of relation types and the entity at the other end will
|
||||
have the opposite relation in the opposite direction (e.g. when querying for
|
||||
`A`, you will see `A.ownedBy.B`, and when querying `B`, you will see
|
||||
`B.ownerOf.A`).
|
||||
|
||||
### `ownedBy` and `ownerOf`
|
||||
|
||||
An ownership relation where the owner is usually an organizational entity
|
||||
([User](descriptor-format.md#kind-user) or
|
||||
[Group](descriptor-format.md#kind-group)), and the other entity can be anything.
|
||||
|
||||
In Backstage, the owner of an entity is the singular entity (commonly a team)
|
||||
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 relation is for display purposes in Backstage, so that people looking at
|
||||
catalog entities 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.
|
||||
|
||||
This relation is commonly generated based on `spec.owner` of the owned entity,
|
||||
where present.
|
||||
|
||||
### `consumesApi` and `providesApi`
|
||||
|
||||
A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
|
||||
[Component](descriptor-format.md#kind-component) or
|
||||
[System](descriptor-format.md#kind-system).
|
||||
|
||||
These relations express that a component or system either exposes an API -
|
||||
meaning that it hosts callable endpoints from which you can consume that API -
|
||||
or that they are dependent on being able to consume that API.
|
||||
|
||||
This relation is commonly generated based on `spec.implementsApis` of the
|
||||
component or system in question.
|
||||
|
||||
### `dependsOn` and `dependencyOf`
|
||||
|
||||
A relation denoting a dependency on another entity.
|
||||
|
||||
This relation is a general expression of being in need of that other entity for
|
||||
an entity to function. It can for example be used to express that a website
|
||||
component needs a library component as part of its build, or that a service
|
||||
component uses a persistent storage resource.
|
||||
|
||||
### `parentOf` and `childOf`
|
||||
|
||||
A parent/child relation to build up a tree, used for example to describe the
|
||||
organizational structure between [Groups](descriptor-format.md#kind-group).
|
||||
|
||||
This relation is commonly based on `spec.parent` and/or `spec.children`.
|
||||
|
||||
### `memberOf` and `hasMember`
|
||||
|
||||
A membership relation, typically for [Users](descriptor-format.md#kind-user) in
|
||||
[Groups](descriptor-format.md#kind-group).
|
||||
|
||||
This relation is commonly based on `spec.memberOf`.
|
||||
Reference in New Issue
Block a user