paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity

Introduce structure for domains, systems and resources

Browse Source
This commit is contained in:
Oliver Sand
2021-01-07 14:13:12 +01:00
parent b8310fdd42
commit 657f7fff6d
3 changed files with 256 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/software-catalog/descriptor-format.md
+243 -3
View File
@@ -382,6 +382,8 @@ spec:
type: website
lifecycle: production
owner: artist-relations@example.com
system: artist-engagement-portal
domain: artists
providesApis:
- artist-api
```
@@ -444,6 +446,22 @@ Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
### `spec.system` [optional]
Links the system that the component belongs to, e.g. `artist-engagement-portal`.
This field is optional.
The software catalog expects a single string that references the name of an
entity of the `kind` `System`.
### `spec.domain` [optional]
Links the domain that the component belongs to, e.g. `artists`. This field is
optional.
The software catalog expects a single string that references the name of an
entity of the `kind` `Domain`.
### `spec.providesApis` [optional]
Links APIs that are provided by the component, e.g. `artist-api`. This field is
@@ -598,6 +616,8 @@ spec:
type: openapi
lifecycle: production
owner: artist-relations@example.com
system: artist-engagement-portal
domain: artists
definition: |
openapi: "3.0.0"
info:
@@ -680,6 +700,22 @@ Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
### `spec.system` [optional]
Links the system that the API belongs to, e.g. `artist-engagement-portal`. This
field is optional.
The software catalog expects a single string that references the name of an
entity of the `kind` `System`.
### `spec.domain` [optional]
Links the domain that the API belongs to, e.g. `artists`. This field is
optional.
The software catalog expects a single string that references the name of an
entity of the `kind` `Domain`.
### `spec.definition` [required]
The definition of the API, based on the format defined by `spec.type`. This
@@ -833,15 +869,219 @@ 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).
Describes the following entity kind:
| Field | Value |
| ------------ | ----------------------- |
| `apiVersion` | `backstage.io/v1alpha1` |
| `kind` | `Resource` |
A resource describes the infrastructure a system needs to operate, like BigTable
databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
components and systems allows to visualize resource footprint, and create
tooling around them.
Descriptor files for this kind may look as follows.
```yaml
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
name: artists-db
description: Stores artist details
spec:
type: database
owner: artist-relations@example.com
domain: artists
system: artist-engagement-portal
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
shape, this kind has the following structure.
### `apiVersion` and `kind` [required]
Exactly equal to `backstage.io/v1alpha1` and `Resource`, respectively.
### `spec.owner` [required]
The owner of the resource, e.g. `artist-relations@example.com`. This field is
required.
In Backstage, the owner of an resource is the singular entity (commonly a team)
that bears ultimate responsibility for the resource, 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 resource belongs. It is
not to be used by automated processes to for example assign authorization in
runtime systems. There may be others that also manage or otherwise touch the
resource, but there will always be one ultimate owner.
Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
### `spec.type` [required]
The type of resource as a string, e.g. `database`. This field is required. There
is currently no enforced set of values for this field, so it is left up to the
adopting organization to choose a nomenclature that matches the resources used
in their tech stack.
Some common values for this field could be:
- `database`
- `s3-bucket`
- `cluster`
### `spec.system` [optional]
Links the system that the resource belongs to, e.g. `artist-engagement-portal`.
This field is optional.
The software catalog expects a single string that references the name of an
entity of the `kind` `System`.
### `spec.domain` [optional]
Links the domain that the resource belongs to, e.g. `artists`. This field is
optional.
The software catalog expects a single string that references the name of an
entity of the `kind` `Domain`.
## Kind: System
This kind is not yet defined, but is reserved [for future use](system-model.md).
Describes the following entity kind:
| Field | Value |
| ------------ | ----------------------- |
| `apiVersion` | `backstage.io/v1alpha1` |
| `kind` | `System` |
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.
Descriptor files for this kind may look as follows.
```yaml
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
name: artist-engagement-portal
description: Handy tools to keep artists in the loop
spec:
owner: artist-relations@example.com
domain: artists
providesApis:
- artist-api
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
shape, this kind has the following structure.
### `apiVersion` and `kind` [required]
Exactly equal to `backstage.io/v1alpha1` and `System`, respectively.
### `spec.owner` [required]
The owner of the System, e.g. `artist-relations@example.com`. This field is
required.
In Backstage, the owner of an System is the singular entity (commonly a team)
that bears ultimate responsibility for the System, 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 System 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 System,
but there will always be one ultimate owner.
Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
### `spec.domain` [optional]
Links the domain that the system belongs to, e.g. `artists`. This field is
optional.
The software catalog expects a single string that references the name of an
entity of the `kind` `Domain`.
### `spec.providesApis` [optional]
Links APIs that are exposed by the system, e.g. `artist-api`, providing
consumers a higher level abstraction on providers of APIs without needing to
have a detailed view in the involved components. This field is optional.
The software catalog expects a list of one or more strings that references the
names of other entities of the `kind` `API`.
### `spec.consumesApis` [optional]
Links APIs that are consumed by the system, e.g. `artist-api`, providing
providers a higher level abstraction on consumers of their APIs without needing
to have a detailed view in the involved components. This field is optional.
The software catalog expects a list of one or more strings that references the
names of other entities of the `kind` `API`.
## Kind: Domain
This kind is not yet defined, but is reserved [for future use](system-model.md).
Describes the following entity kind:
| Field | Value |
| ------------ | ----------------------- |
| `apiVersion` | `backstage.io/v1alpha1` |
| `kind` | `Domain` |
A Domain groups a collection of systems that share terminology, domain models,
business purpose, or documentation, i.e. form a bounded context.
Descriptor files for this kind may look as follows.
```yaml
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
name: artists
description: Everything about artists
spec:
owner: artist-relations@example.com
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
shape, this kind has the following structure.
### `apiVersion` and `kind` [required]
Exactly equal to `backstage.io/v1alpha1` and `Domain`, respectively.
### `spec.owner` [required]
The owner of the domain, e.g. `artist-relations@example.com`. This field is
required.
In Backstage, the owner of an domain is the singular entity (commonly a team)
that bears ultimate responsibility for the domain, 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 system 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 system,
but there will always be one ultimate owner.
Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
## Kind: Location
docs/features/software-catalog/system-model.md
-4
View File
@@ -107,10 +107,6 @@ product or use-case, share the same entity types in their APIs, and integrate
well with each other. Other domains could be “Content Ingestion”, “Ads” or
“Search”.
## Current status
Backstage currently supports Components and APIs.
## Links
- [Original RFC](https://github.com/backstage/backstage/issues/390)
docs/features/software-catalog/well-known-relations.md
+13
View File
@@ -91,3 +91,16 @@ 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`.
### `partOf` and `hasPart`
A relation with an [Domain](descriptor-format.md#kind-domain) or
[System](descriptor-format.md#kind-system) entity, typically from a
[Component](descriptor-format.md#kind-component),
[API](descriptor-format.md#kind-api), or
[System](descriptor-format.md#kind-system).
These relations express that a component, API, or system belongs to or is
grouped under a system or domain.
This relation is commonly based on `spec.system` or `spec.domain`.