From 657f7fff6d545ab0035e160871c5b092208b63d6 Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Thu, 7 Jan 2021 14:13:12 +0100 Subject: [PATCH 1/8] Introduce structure for domains, systems and resources --- .../software-catalog/descriptor-format.md | 246 +++++++++++++++++- .../features/software-catalog/system-model.md | 4 - .../software-catalog/well-known-relations.md | 13 + 3 files changed, 256 insertions(+), 7 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 763acd2261..53f7330d37 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -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 diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md index d797e87499..e9a801fcd2 100644 --- a/docs/features/software-catalog/system-model.md +++ b/docs/features/software-catalog/system-model.md @@ -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) diff --git a/docs/features/software-catalog/well-known-relations.md b/docs/features/software-catalog/well-known-relations.md index 54f7833d1b..7c03165a95 100644 --- a/docs/features/software-catalog/well-known-relations.md +++ b/docs/features/software-catalog/well-known-relations.md @@ -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`. From 9795d529d3d6f501a7c396981b74510ba5ecc85e Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Fri, 8 Jan 2021 09:21:39 +0100 Subject: [PATCH 2/8] Make domain only a reference of a system --- .../software-catalog/descriptor-format.md | 27 ------------------- 1 file changed, 27 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 53f7330d37..17fb274b35 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -383,7 +383,6 @@ spec: lifecycle: production owner: artist-relations@example.com system: artist-engagement-portal - domain: artists providesApis: - artist-api ``` @@ -454,14 +453,6 @@ 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 @@ -617,7 +608,6 @@ spec: lifecycle: production owner: artist-relations@example.com system: artist-engagement-portal - domain: artists definition: | openapi: "3.0.0" info: @@ -708,14 +698,6 @@ 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 @@ -892,7 +874,6 @@ metadata: spec: type: database owner: artist-relations@example.com - domain: artists system: artist-engagement-portal ``` @@ -943,14 +924,6 @@ 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 Describes the following entity kind: From 541cff1a2f2c87ee59ccc830e12848577f1da46e Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Fri, 8 Jan 2021 09:41:16 +0100 Subject: [PATCH 3/8] Introduce a general way to mark entity references --- docs/features/software-catalog/descriptor-format.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 17fb274b35..ecc6946299 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -447,11 +447,16 @@ 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. +An [entity reference](#string-references) that to 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`. +| Default [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| ----------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| [`System`](#kind-system) (only) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | + +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| [`System`](#kind-system) (default), [`API`](#kind-system) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | ### `spec.providesApis` [optional] From 4254f760f54347c520f1f29d955426e1f2c3e31e Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Fri, 8 Jan 2021 17:30:08 +0100 Subject: [PATCH 4/8] Use the table for all entity references --- .../software-catalog/descriptor-format.md | 162 ++++++++++-------- 1 file changed, 88 insertions(+), 74 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index ecc6946299..220a4e8933 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -428,8 +428,8 @@ The current set of well-known and common values for this field is: ### `spec.owner` [required] -The owner of the component, e.g. `artist-relations@example.com`. This field is -required. +An [entity reference](#string-references) to the owner of the component, e.g. +`artist-relations@example.com`. This field is required. In Backstage, the owner of a component is the singular entity (commonly a team) that bears ultimate responsibility for the component, and has the authority and @@ -441,38 +441,36 @@ 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 component, 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`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) | ### `spec.system` [optional] -An [entity reference](#string-references) that to the system that the component +An [entity reference](#string-references) to the system that the component belongs to, e.g. `artist-engagement-portal`. This field is optional. -| Default [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | -| ----------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | -| [`System`](#kind-system) (only) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | - -| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | -| --------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | -| [`System`](#kind-system) (default), [`API`](#kind-system) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | ### `spec.providesApis` [optional] -Links APIs that are provided by the component, e.g. `artist-api`. This field is -optional. +An array of [entity reference](#string-references) to the APIs that are provided +by the component, e.g. `artist-api`. 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`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | +| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`providesApi`, and reverse `apiProvidedBy`](well-known-relations.md#providesapi-and-apiprovidedby) | ### `spec.consumesApis` [optional] -Links APIs that are consumed by the component, e.g. `artist-api`. This field is -optional. +An array of [entity reference](#string-references) to the APIs that are consumed +by the component, e.g. `artist-api`. 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`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | +| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`consumesApi`, and reverse `apiConsumedBy`](well-known-relations.md#consumesapi-and-apiconsumedby) | ## Kind: Template @@ -678,8 +676,8 @@ The current set of well-known and common values for this field is: ### `spec.owner` [required] -The owner of the API, e.g. `artist-relations@example.com`. This field is -required. +An [entity reference](#string-references) to the owner of the component, e.g. +`artist-relations@example.com`. This field is required. In Backstage, the owner of an API is the singular entity (commonly a team) that bears ultimate responsibility for the API, and has the authority and capability @@ -691,17 +689,18 @@ processes to for example assign authorization in runtime systems. There may be others that also develop or otherwise touch the API, 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`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) | ### `spec.system` [optional] -Links the system that the API belongs to, e.g. `artist-engagement-portal`. This -field is optional. +An [entity reference](#string-references) to 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`. +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | ### `spec.definition` [required] @@ -774,11 +773,11 @@ parent; the catalog supports multi-root hierarchies. Groups may however not have more than one parent. This field is an -[entity reference](https://backstage.io/docs/features/software-catalog/references), -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, -this field points to a group in the same namespace, so in those cases it is -sufficient to enter only the `metadata.name` field of that group. +[entity reference](https://backstage.io/docs/features/software-catalog/references). + +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`childOf`, and reverse `parentOf`](well-known-relations.md#parentof-and-childof) | ### `spec.children` [required] @@ -788,11 +787,11 @@ no child groups. The items are not guaranteed to be ordered in any particular way. The entries of this array are -[entity references](https://backstage.io/docs/features/software-catalog/references), -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. +[entity references](https://backstage.io/docs/features/software-catalog/references). + +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`hasMember`, and reverse `memberOf`](well-known-relations.md#memberof-and-hasmember) | ## Kind: User @@ -848,7 +847,12 @@ user is not member of any groups. The items are not guaranteed to be ordered in any particular way. The entries of this array are -[entity references](https://backstage.io/docs/features/software-catalog/references), +[entity references](https://backstage.io/docs/features/software-catalog/references). + +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`memberOf`, and reverse `hasMember`](well-known-relations.md#memberof-and-hasmember) | + 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 @@ -891,8 +895,8 @@ 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. +An [entity reference](#string-references) to the owner of the component, 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 @@ -904,9 +908,9 @@ 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. +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) | ### `spec.type` [required] @@ -923,11 +927,12 @@ Some common values for this field could be: ### `spec.system` [optional] -Links the system that the resource belongs to, e.g. `artist-engagement-portal`. -This field is optional. +An [entity reference](#string-references) to 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`. +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | ## Kind: System @@ -968,8 +973,8 @@ 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. +An [entity reference](#string-references) to 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 @@ -981,35 +986,44 @@ 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`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) | ### `spec.domain` [optional] -Links the domain that the system belongs to, e.g. `artists`. This field is -optional. +An [entity reference](#string-references) to 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`. +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | +| [`Domain`](#kind-domain) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | ### `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. +An array of [entity reference](#string-references) to the APIs that are provided +by the system, e.g. `artist-api`. 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`. +APIs can be exposed by the system, providing consumers a higher level +abstraction on providers of APIs without needing to have a detailed view in the +involved components. + +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | +| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`providesApi`, and reverse `apiProvidedBy`](well-known-relations.md#providesapi-and-apiprovidedby) | ### `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. +An array of [entity reference](#string-references) to the APIs that are consumed +by the system, e.g. `artist-api`. 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`. +APIs can be consumed by the system, 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. + +| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | +| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`consumesApi`, and reverse `apiConsumedBy`](well-known-relations.md#consumesapi-and-apiconsumedby) | ## Kind: Domain @@ -1044,8 +1058,8 @@ 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. +An [entity reference](#string-references) to 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 @@ -1057,9 +1071,9 @@ 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`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | +| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- | +| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) | ## Kind: Location From feded2d252841da0d73a7c2dec77eceb9da928bf Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Mon, 11 Jan 2021 20:23:52 +0100 Subject: [PATCH 5/8] Include review comments --- .../software-catalog/descriptor-format.md | 63 +++++++++---------- .../software-catalog/well-known-relations.md | 6 +- 2 files changed, 32 insertions(+), 37 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 220a4e8933..750cbcfe1a 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -60,7 +60,7 @@ software catalog API. }, "spec": { "lifecycle": "production", - "owner": "artist-relations@example.com", + "owner": "artist-relations-team", "type": "website" } } @@ -84,7 +84,7 @@ metadata: spec: type: website lifecycle: production - owner: artist-relations@example.com + owner: artist-relations-team ``` The root fields `apiVersion`, `kind`, `metadata`, and `spec` are part of the @@ -381,7 +381,7 @@ metadata: spec: type: website lifecycle: production - owner: artist-relations@example.com + owner: artist-relations-team system: artist-engagement-portal providesApis: - artist-api @@ -429,7 +429,7 @@ The current set of well-known and common values for this field is: ### `spec.owner` [required] An [entity reference](#string-references) to the owner of the component, e.g. -`artist-relations@example.com`. This field is required. +`artist-relations-team`. This field is required. In Backstage, the owner of a component is the singular entity (commonly a team) that bears ultimate responsibility for the component, and has the authority and @@ -456,8 +456,8 @@ belongs to, e.g. `artist-engagement-portal`. This field is optional. ### `spec.providesApis` [optional] -An array of [entity reference](#string-references) to the APIs that are provided -by the component, e.g. `artist-api`. This field is optional. +An array of [entity references](#string-references) to the APIs that are +provided by the component, e.g. `artist-api`. This field is optional. | [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | | --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | @@ -465,8 +465,8 @@ by the component, e.g. `artist-api`. This field is optional. ### `spec.consumesApis` [optional] -An array of [entity reference](#string-references) to the APIs that are consumed -by the component, e.g. `artist-api`. This field is optional. +An array of [entity references](#string-references) to the APIs that are +consumed by the component, e.g. `artist-api`. This field is optional. | [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | | --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | @@ -609,7 +609,7 @@ metadata: spec: type: openapi lifecycle: production - owner: artist-relations@example.com + owner: artist-relations-team system: artist-engagement-portal definition: | openapi: "3.0.0" @@ -677,7 +677,7 @@ The current set of well-known and common values for this field is: ### `spec.owner` [required] An [entity reference](#string-references) to the owner of the component, e.g. -`artist-relations@example.com`. This field is required. +`artist-relations-team`. This field is required. In Backstage, the owner of an API is the singular entity (commonly a team) that bears ultimate responsibility for the API, and has the authority and capability @@ -853,11 +853,6 @@ The entries of this array are | --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- | | [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`memberOf`, and reverse `hasMember`](well-known-relations.md#memberof-and-hasmember) | -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 Describes the following entity kind: @@ -882,7 +877,7 @@ metadata: description: Stores artist details spec: type: database - owner: artist-relations@example.com + owner: artist-relations-team system: artist-engagement-portal ``` @@ -895,10 +890,10 @@ Exactly equal to `backstage.io/v1alpha1` and `Resource`, respectively. ### `spec.owner` [required] -An [entity reference](#string-references) to the owner of the component, e.g. -`artist-relations@example.com`. This field is required. +An [entity reference](#string-references) to the owner of the resource, e.g. +`artist-relations-team`. This field is required. -In Backstage, the owner of an resource is the singular entity (commonly a team) +In Backstage, the owner of a 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 @@ -958,7 +953,7 @@ metadata: name: artist-engagement-portal description: Handy tools to keep artists in the loop spec: - owner: artist-relations@example.com + owner: artist-relations-team domain: artists providesApis: - artist-api @@ -974,16 +969,16 @@ Exactly equal to `backstage.io/v1alpha1` and `System`, respectively. ### `spec.owner` [required] An [entity reference](#string-references) to the owner of the system, e.g. -`artist-relations@example.com`. This field is required. +`artist-relations-team`. 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 +In Backstage, the owner of a 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 +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, +systems. There may be others that also develop or otherwise touch the system, but there will always be one ultimate owner. | [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | @@ -1001,8 +996,8 @@ to, e.g. `artists`. This field is optional. ### `spec.providesApis` [optional] -An array of [entity reference](#string-references) to the APIs that are provided -by the system, e.g. `artist-api`. This field is optional. +An array of [entity references](#string-references) to the APIs that are +provided by the system, e.g. `artist-api`. This field is optional. APIs can be exposed by the system, providing consumers a higher level abstraction on providers of APIs without needing to have a detailed view in the @@ -1014,8 +1009,8 @@ involved components. ### `spec.consumesApis` [optional] -An array of [entity reference](#string-references) to the APIs that are consumed -by the system, e.g. `artist-api`. This field is optional. +An array of [entity references](#string-references) to the APIs that are +consumed by the system, e.g. `artist-api`. This field is optional. APIs can be consumed by the system, providing providers a higher level abstraction on consumers of their APIs without needing to have a detailed view @@ -1046,7 +1041,7 @@ metadata: name: artists description: Everything about artists spec: - owner: artist-relations@example.com + owner: artist-relations-team ``` In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata) @@ -1059,16 +1054,16 @@ Exactly equal to `backstage.io/v1alpha1` and `Domain`, respectively. ### `spec.owner` [required] An [entity reference](#string-references) to the owner of the domain, e.g. -`artist-relations@example.com`. This field is required. +`artist-relations-team`. This field is required. -In Backstage, the owner of an domain is the singular entity (commonly a team) +In Backstage, the owner of a 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 +catalog items can get an understanding of to whom this domain 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, +systems. There may be others that also develop or otherwise touch the domain, but there will always be one ultimate owner. | [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | diff --git a/docs/features/software-catalog/well-known-relations.md b/docs/features/software-catalog/well-known-relations.md index 7c03165a95..daebd32701 100644 --- a/docs/features/software-catalog/well-known-relations.md +++ b/docs/features/software-catalog/well-known-relations.md @@ -94,13 +94,13 @@ This relation is commonly based on `spec.memberOf`. ### `partOf` and `hasPart` -A relation with an [Domain](descriptor-format.md#kind-domain) or +A relation with a [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. +These relations express that a component, API or resource belongs to a system, +or that a system is grouped under a domain. This relation is commonly based on `spec.system` or `spec.domain`. From 15432e61f16a9fed9a831e1f860b08bce7bfa451 Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Mon, 11 Jan 2021 20:56:55 +0100 Subject: [PATCH 6/8] Rework system model diagrams as drawio files --- .../software-model-core-entities.drawio.svg | 3 +++ .../software-model-core-entities.png | Bin 7235 -> 0 bytes .../software-model-entities.drawio.svg | 3 +++ docs/features/software-catalog/system-model.md | 4 +++- 4 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 docs/assets/software-catalog/software-model-core-entities.drawio.svg delete mode 100644 docs/assets/software-catalog/software-model-core-entities.png create mode 100644 docs/assets/software-catalog/software-model-entities.drawio.svg diff --git a/docs/assets/software-catalog/software-model-core-entities.drawio.svg b/docs/assets/software-catalog/software-model-core-entities.drawio.svg new file mode 100644 index 0000000000..032944659c --- /dev/null +++ b/docs/assets/software-catalog/software-model-core-entities.drawio.svg @@ -0,0 +1,3 @@ + + +
attachesTo
attachesTo
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
Component
(e.g. backend service, data pipeline ...)
Component...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/assets/software-catalog/software-model-core-entities.png b/docs/assets/software-catalog/software-model-core-entities.png deleted file mode 100644 index 60cb283802fe001bf0c1031df0d447edf02ab6d4..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 7235 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 + +
Domain
Domain
partOf
partOf
consumesApi
consumesApi
System
System
attachesTo
attachesTo
partOf
partOf
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
partOf
partOf
Component
(e.g. backend service, data pipeline ...)
Component...
partOf
partOf
providesApi
providesApiViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md index e9a801fcd2..f0ead20664 100644 --- a/docs/features/software-catalog/system-model.md +++ b/docs/features/software-catalog/system-model.md @@ -23,7 +23,7 @@ We model software in the Backstage catalogue using these three core entities - **Resources** are physical or virtual infrastructure needed to operate a component -![](../../assets/software-catalog/software-model-core-entities.png) +![](../../assets/software-catalog/software-model-core-entities.drawio.svg) ### Component @@ -73,6 +73,8 @@ these entities using the following (optional) concepts: function - **Domains** relate entities and systems to part of the business +![](../../assets/software-catalog/software-model-entities.drawio.svg) + ### System With increasing complexity in software, systems form an important abstraction From 580b4cad8e43e651d7612cace5463a174158d479 Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Mon, 11 Jan 2021 22:09:59 +0100 Subject: [PATCH 7/8] Use dependsOn between components and resources for now --- .../software-catalog/software-model-core-entities.drawio.svg | 2 +- docs/assets/software-catalog/software-model-entities.drawio.svg | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/assets/software-catalog/software-model-core-entities.drawio.svg b/docs/assets/software-catalog/software-model-core-entities.drawio.svg index 032944659c..2260e5502e 100644 --- a/docs/assets/software-catalog/software-model-core-entities.drawio.svg +++ b/docs/assets/software-catalog/software-model-core-entities.drawio.svg @@ -1,3 +1,3 @@ -
attachesTo
attachesTo
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
Component
(e.g. backend service, data pipeline ...)
Component...Viewer does not support full SVG 1.1 \ No newline at end of file +
dependsOn
dependsOn
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
Component
(e.g. backend service, data pipeline ...)
Component...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/assets/software-catalog/software-model-entities.drawio.svg b/docs/assets/software-catalog/software-model-entities.drawio.svg index eeea79f610..0105138fa0 100644 --- a/docs/assets/software-catalog/software-model-entities.drawio.svg +++ b/docs/assets/software-catalog/software-model-entities.drawio.svg @@ -1,3 +1,3 @@ -
Domain
Domain
partOf
partOf
consumesApi
consumesApi
System
System
attachesTo
attachesTo
partOf
partOf
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
partOf
partOf
Component
(e.g. backend service, data pipeline ...)
Component...
partOf
partOf
providesApi
providesApiViewer does not support full SVG 1.1 \ No newline at end of file +
Domain
Domain
partOf
partOf
consumesApi
consumesApi
System
System
dependsOn
dependsOn
partOf
partOf
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
partOf
partOf
Component
(e.g. backend service, data pipeline ...)
Component...
partOf
partOf
providesApi
providesApiViewer does not support full SVG 1.1 \ No newline at end of file From c773e00d54b8f1b2c788a70c31d4db127fc188ce Mon Sep 17 00:00:00 2001 From: Oliver Sand Date: Tue, 12 Jan 2021 15:05:47 +0100 Subject: [PATCH 8/8] Remove providesApis and consumesApis from systems We can later add them again. --- .../software-model-entities.drawio.svg | 2 +- .../software-catalog/descriptor-format.md | 26 ------------------- .../software-catalog/well-known-relations.md | 14 +++++----- 3 files changed, 7 insertions(+), 35 deletions(-) diff --git a/docs/assets/software-catalog/software-model-entities.drawio.svg b/docs/assets/software-catalog/software-model-entities.drawio.svg index 0105138fa0..7b8b88f224 100644 --- a/docs/assets/software-catalog/software-model-entities.drawio.svg +++ b/docs/assets/software-catalog/software-model-entities.drawio.svg @@ -1,3 +1,3 @@ -
Domain
Domain
partOf
partOf
consumesApi
consumesApi
System
System
dependsOn
dependsOn
partOf
partOf
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
partOf
partOf
Component
(e.g. backend service, data pipeline ...)
Component...
partOf
partOf
providesApi
providesApiViewer does not support full SVG 1.1 \ No newline at end of file +
Domain
Domain
partOf
partOf
System
System
dependsOn
dependsOn
partOf
partOf
Resource
(e.g. SQL Database, S3 bucket, ...)
Resource...
consumesAPI
consumesAPI
API
(e.g. OpenAPI, gRPC API, Avro, Dataset, ...)
API...
providesAPI
providesAPI
partOf
partOf
Component
(e.g. backend service, data pipeline ...)
Component...
partOf
partOfViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 750cbcfe1a..725f358b92 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -994,32 +994,6 @@ to, e.g. `artists`. This field is optional. | --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | | [`Domain`](#kind-domain) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | -### `spec.providesApis` [optional] - -An array of [entity references](#string-references) to the APIs that are -provided by the system, e.g. `artist-api`. This field is optional. - -APIs can be exposed by the system, providing consumers a higher level -abstraction on providers of APIs without needing to have a detailed view in the -involved components. - -| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | -| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | -| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`providesApi`, and reverse `apiProvidedBy`](well-known-relations.md#providesapi-and-apiprovidedby) | - -### `spec.consumesApis` [optional] - -An array of [entity references](#string-references) to the APIs that are -consumed by the system, e.g. `artist-api`. This field is optional. - -APIs can be consumed by the system, 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. - -| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type | -| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | -| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`consumesApi`, and reverse `apiConsumedBy`](well-known-relations.md#consumesapi-and-apiconsumedby) | - ## Kind: Domain Describes the following entity kind: diff --git a/docs/features/software-catalog/well-known-relations.md b/docs/features/software-catalog/well-known-relations.md index daebd32701..af2e7367f2 100644 --- a/docs/features/software-catalog/well-known-relations.md +++ b/docs/features/software-catalog/well-known-relations.md @@ -48,11 +48,10 @@ where present. ### `providesApi` and `apiProvidedBy` 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). +[Component](descriptor-format.md#kind-component). -These relations express that a component or system exposes an API - meaning that -it hosts callable endpoints from which you can consume that API. +These relations express that a component exposes an API - meaning that it hosts +callable endpoints from which you can consume that API. This relation is commonly generated based on `spec.providesApis` of the component or system in question. @@ -60,11 +59,10 @@ component or system in question. ### `consumesApi` and `apiConsumedBy` 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). +[Component](descriptor-format.md#kind-component). -These relations express that a component or system consumes an API - meaning -that it depends on endpoints of the API. +These relations express that a component consumes an API - meaning that it +depends on endpoints of the API. This relation is commonly generated based on `spec.consumesApis` of the component or system in question.