目录实体描述符格式

本节介绍目录实体的默认数据形状和语义。

这既适用于向软件编目 API 提供和从 API 返回的对象，也适用于软件编目可以本地摄取的描述符文件。在 API 的请求/响应循环中，使用的是 JSON 表示法，而描述符文件则采用 YAML 格式，以便于人工维护。不过，这两种情况下的结构和语义是相同的。

虽然目录实体描述符文件可以随意命名，但我们建议命名为catalog-info.yaml.

内容

Overall Shape Of An Entity * Common to All Kinds: The Envelope * Common to All Kinds: The Metadata * Common to All Kinds: Relations * Common to All Kinds: Status * Kind: Component * Kind: Template * Kind: API * Kind: Group * Kind: User * Kind: Resource * Kind: System * Kind: Domain * Kind: Location

实体的整体形状

下面是组件实体描述符文件的示例：

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
  labels:
    example.com/custom: custom_label_value
  annotations:
    example.com/service-discovery: artistweb
    circleci.com/project-slug: github/example-org/artist-website
  tags:
    - java
  links:
    - url: https://admin.example-org.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: website
  lifecycle: production
  owner: artist-relations-team
  system: public-websites

这与软件目录 API 返回的 JSON 格式实体相同：

{
  "apiVersion": "backstage.io/v1alpha1",
  "kind": "Component",
  "metadata": {
    "annotations": {
      "backstage.io/managed-by-location": "file:/tmp/catalog-info.yaml",
      "example.com/service-discovery": "artistweb",
      "circleci.com/project-slug": "github/example-org/artist-website"
    },
    "description": "The place to be, for great artists",
    "etag": "ZjU2MWRkZWUtMmMxZS00YTZiLWFmMWMtOTE1NGNiZDdlYzNk",
    "labels": {
      "example.com/custom": "custom_label_value"
    },
    "links": [
      {
        "url": "https://admin.example-org.com",
        "title": "Admin Dashboard",
        "icon": "dashboard",
        "type": "admin-dashboard"
      }
    ],
    "tags": ["java"],
    "name": "artist-web",
    "uid": "2152f463-549d-4d8d-a94d-ce2b7676c6e2"
  },
  "spec": {
    "lifecycle": "production",
    "owner": "artist-relations-team",
    "type": "website",
    "system": "public-websites"
  }
}

根字段apiVersion,kind,metadata和spec是_信封同样，一些元数据字段，如name,labels和annotations它们具有特殊的意义，并有特定的用途和独特的形状。

有关这些字段的详细信息，请参阅下文。

描述符格式中的替换

描述符格式支持使用以下方法进行替换$text,$json和$yaml.

占位符，如$json: https://example.com/entity.json被引用文件的内容所替代。文件可以从任何配置的集成中引用，类似于通过传递绝对 URL 引用位置。也可以引用相对文件，如./referenced.yaml相对引用的处理是相对于catalog-info.yaml有三种不同类型的占位符：

$text: 将引用文件的内容解释为纯文本，并将其嵌入为字符串。 $json: 将引用文件的内容解释为 JSON，并嵌入解析后的结构。 $yaml: 将引用文件的内容解释为 YAML，并嵌入解析后的结构。

例如，这可用于从网络服务器加载 API 实体的定义，并将其作为字符串嵌入字段中spec.definition:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: petstore
  description: The Petstore API
spec:
  type: openapi
  lifecycle: production
  owner: [email protected]
  definition:
    $text: https://petstore.swagger.io/v2/swagger.json

请注意，要读取正常集成点以外的目标，如github.com中添加一个条目来明确允许它。backend.reading.allow例如，可以指定路径来进一步限制目标：

backend:
  baseUrl: ...
  reading:
    allow:
      - host: example.com
      - host: '*.examples.org'
      - host: example.net
        paths: ['/api/']

所有种类的共同点：信封

根信封对象的结构如下

`apiVersion` 和 `kind` [必填]

kind是描述的高层实体类型。ADR005描述了一些插件可以知道和理解的核心种类，但使用 Backstage 的组织也可以自由地在目录中添加其他种类的实体。

目录在初始阶段关注的最核心的实体可能是Component(见下).

apiVersion是规范所针对的特定实体的规范格式的版本。版本用于格式的演进，而apiVersion和kind应该足以让解析器知道如何解释其余数据的内容。

Backstage特定实体有一个apiVersion的backstage.io/在将这些规范与 Kubernetes 对象清单等共同托管时，或在组织向目录中添加自己特定类型的实体时，这一点可能很重要。

早期版本的目录将使用 alpha/beta 版本，例如backstage.io/v1alpha1之后，我们将使用backstage.io/v1及以上。

`metadata` [必填]

包含实体元数据的结构，即不直接属于实体规范本身的内容。有关此结构的更多详情，请参阅下文。

`spec` [varies] [不同]

描述实体的实际规范数据。

的确切结构spec取决于apiVersion和kind组合，有些种类甚至可能没有spec有关具体类型的规范结构，请参见本文档的后续内容。

所有类型的共同点：元数据

metadata根字段有一些具有特定含义的保留字段，如下所述。

除此以外，您还可以直接在以下字段中添加任意数量的其他字段metadata但请注意，一般的插件和工具可能无法理解它们的语义。参见扩展模型了解更多信息。

`name` [必填]

实体名称：该名称既可用于人眼识别实体，也可用于机器和其他组件引用实体(如 URL 或其他实体规范文件)。

在给定的名称空间(如有指定)内，名称在任何时间点都必须是唯一的。这种唯一性约束不区分大小写。从注册表中删除实体后，名称可在以后重复使用。

名称必须遵循一定的格式。不遵循这些规则的实体将不被接受在目录中注册。规则集可根据贵组织的需要进行配置，但默认行为如下。

长度至少为 1，最多为 63 的字符串 * 必须由"[a-z0-9A-Z]"序列组成，可能由"[-_.]"分隔。

例如visits-tracking-service,CircleciBuildsDumpV2_avro_gcs

`namespace` [可选]

实体所属命名空间的 ID。该字段为可选字段，目前除了用于约束名称唯一性(如果指定)外，没有其他特殊语义。该字段保留给将来使用，以后可能会有更广泛的语义含义。

目前，建议不要指定名称空间，除非有特殊需要。"default"命名空间。

命名空间必须是[a-zA-Z0-9]，可能以-命名空间名称不区分大小写，在大多数情况下会以小写字母显示。

例如tracking-services,payment

`uid` [输出]

每个实体在首次进入数据库时都会获得一个自动生成的全局唯一 ID，这个字段不是作为输入数据指定的，而是由数据库引擎在生成输出实体时自行创建的。

请注意uid值为不是被视为稳定，并应不是可用作实体的外部引用。uid即使人类观察者可能认为它不会随时间而改变，它也会随时间而改变。作为众多例子之一，取消注册和重新注册完全相同的文件会导致不同的uid因此，很少有理由从外部读取或使用该字段。

如果要通过某种形式的标识符来引用实体，应始终使用字符串形式的实体引用而不是

`title` [可选]

实体的显示名称，用于在用户界面中显示，而不是使用name如果有的话，可以使用上述属性。

当name标题一般没有那么严格的格式要求，因此可以包含特殊字符，解释性更强。但一定要简短，避免标题与其他实体的名称相混淆，或两个实体共用一个标题。

请注意，这仅用于显示目的，代码的某些部分可能会忽略它。实体参考仍然经常使用name而不是标题。

`description` [可选]

对实体的可读描述，显示在 Backstage 中。应保持简短和信息丰富，适合一目了然地概述实体的目的。更详细的解释和文档应放在其他地方。

`labels` [可选]

标签是附加到实体的可选键/值对，其用法与Kubernetes 对象标签.

它们的主要用途是对其他实体的引用，以及以某种方式对当前实体进行分类的信息。它们通常用作查询或筛选器中的值。

键和值都是字符串，但有以下限制。

键值有一个可选的前缀，后面跟一个斜线，然后是必须的名称部分。如果有前缀，前缀必须是一个有效的小写域名，总共最多 253 个字符。名称部分必须是以下的序列[a-zA-Z0-9]任何一个[-_.]总共最多 63 个字符。

backstage.io/前缀保留给Backstage核心组件使用。

值是字符串，其限制与name以上。

`annotations` [可选]

一个对象，实体上附有任意的非标识性元数据，在使用上与Kubernetes 对象注解.

用户可以在描述符 YAML 文件中添加这些注释，但除此之外，自动化系统也可以添加注释，可以在编录过程中添加，也可以在稍后添加。

键和值都是字符串，但有以下限制。

键值有一个可选的前缀，后面跟一个斜线，然后是必填的名称部分。如果指定了前缀，前缀必须是一个有效的小写域名，总共最多 253 个字符。名称部分必须是以下的序列[a-zA-Z0-9]任何一个[-_.]总共最多 63 个字符。

backstage.io/前缀保留给Backstage核心组件使用。

值的长度不限，但仅限于字符串。

有一份知名注释但任何人都可以自由添加他们认为合适的注释。

`tags` [可选]

单值字符串列表，用于以各种方式对目录实体进行分类。这与元数据中的标签不同，因为标签是键值对。

数值由用户定义，例如组件使用的编程语言，如java或go.

该字段为可选字段，目前没有特殊语义。

每个标记的序列必须是[a-z0-9:+#]相隔-总共最多 63 个字符。

`links` [可选]

与实体相关的外部超链接列表。链接可提供Backstage本身以外的其他上下文信息。例如，管理仪表板或外部内容管理系统页面。

用户可以在描述符 YAML 文件中添加链接，以便为外部内容和资源提供额外的参考信息。链接的目的不是为了在 Backstage 中驱动任何额外的功能，这些功能最好交由annotations和labels建议仅在有同等知名度的情况下使用链接。annotation并不涵盖类似的用例。

链接的字段有

| 字段 | 类型 | 说明 | | ------- | ------ | ------------------------------------------------------------------------------------ | | | |url| 字符串[必填]Aurl在标准uri格式(例如https://example.com/some/page) | |title| 字符串[可选]链接的用户友好显示名称。icon| 字符串[可选]表示要在用户界面中显示的可视化图标的键。type| 字符串[可选]可选值，用于将链接归入特定组别。

_注："......icon字段值是一个语义键，可映射到图标库提供的特定图标(例如material-ui这些键应该是一连串的[a-z0-9A-Z]，可能由以下其中一个分隔[-_.]Backstage 可能支持一些开箱即用的基本图标，例如在 app-defaults 中定义如果无法解决映射问题，将提供一个通用的后备图标。

的语义。type采用者可自由定义自己的类型集，并按自己的意愿加以利用。一些潜在的用例可以是利用类型字段来验证实体上是否存在某些链接，或为特定链接类型创建定制的用户界面组件。

所有种类的共同点：关系

relations根字段是当前实体与其他实体之间关系的只读列表。知名关系科关系通常是双向的，因此有一对关系类型，每个类型描述关系的一个方向。

作为从应用程序接口读出的单一实体的一部分，关系可能如下所示。

{
  // ...
  "relations": [
    {
      "type": "ownedBy",
      "targetRef": "group:default/dev.infra"
    }
  ],
  "spec": {
    "owner": "dev.infra",
    // ...
  }
}

关系的字段有

| 字段 | 类型 | 说明 | | ----------- | ------ | -------------------------------------------------------------------------- | | | |targetRef| 字符串实体参考到关系的另一端。type| 字符串 | 从源实体到目标实体的关系类型。metadata| 对象 | 保留供将来使用。

实体描述符 YAML 文件不应该包含这个字段，相反，目录处理器会分析实体描述符数据及其周围环境，并推导出关系，然后将这些关系附加到从目录读取的实体上。

在产生关系的地方，它们应被视为该数据的权威来源。在上面的例子中，插件最好使用关系，而不是spec.owner来推断实体的所有者，因为甚至可能根本不是从 YAML 中获取所有者信息，而是从附近的 CODEOWNERS 文件中获取。此外，Ownersspec.owner是简写形式，可能有与之相关的语义(例如默认类型为Group如果未指定)。

参见知名关系科中列出的知名/常见关系及其语义。

所有类型的共同点：状态

status根对象是一组只读状态，与实体的当前状态或健康状况有关，在知名状态部分.

目前，唯一定义的字段是items数组中的每个项都包含一个特定的数据结构，从某个特定系统的角度来描述实体状态的某些方面。不同的系统可以根据各自的type钥匙

该字段的当前主要用途是用于目录本身的摄取流程，以便将错误和警告信息反馈给用户。

作为从应用程序接口读出的单一实体的一部分，状态字段可能如下所示。

{
  // ...
  "status": {
    "items": [
      {
        "type": "backstage.io/catalog-processing",
        "level": "error",
        "message": "NotFoundError: File not found",
        "error": {
          "name": "NotFoundError",
          "message": "File not found",
          "stack": "..."
        }
      }
    ]
  },
  "spec": {
    // ...
  }
}

状态项目的字段有

| 字段 | 类型 | 说明 | | --------- | ------ | ------------------------------------------------------------------------------------------------ | | | |type| 字符串 | 状态类型，作为每个信息源的唯一关键字。每种类型在数组中可能出现多次。level| 状态项的级别/严重程度："info"(信息)、"warning"(警告)或 "error"(错误)。message| 字符串 | 描述状态的简短信息，供人阅读。error| 与状态相关的可选序列化错误对象。

type是一个任意字符串，但我们建议对组织内部非严格私有的类型进行命名，以避免碰撞。例如，Backstage核心进程发出的类型将以backstage.io/如上例所示。

实体描述符 YAML 文件不应包含status取而代之的是，目录处理器分析实体描述符数据及其周围环境，并推导出状态条目，然后从目录中读取附加到实体上。

参见知名状态部分查看知名/常见状态类型列表。

类型：组件

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|Component|

组件描述的是一个软件组件，通常与构成该组件的源代码密切相关，应被开发人员视为一个 "软件单元"，通常具有独特的可部署或可链接的工件。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
spec:
  type: website
  lifecycle: production
  owner: artist-relations-team
  system: artist-engagement-portal
  dependsOn:
    - resource:default/artists-db
  providesApis:
    - artist-api

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和Component分别为

`spec.type` [必填]

以字符串形式表示的组件类型，例如website该字段为必填字段。

软件目录接受任何类型的值，但组织应非常小心地为这些类型建立适当的分类。包括Backstage本身在内的工具可能会读取该字段，并根据其值采取不同的行为。例如，网站类型组件可能会在Backstage界面中显示专门针对网站的工具。

该字段的当前常用值为

服务"--后端服务，通常公开一个应用程序接口 * "网站"--网站 * "库"--软件库，如 npm 模块或 Java 库

`spec.lifecycle` [必填]

组件的生命周期状态，例如production该字段为必填字段。

软件目录可接受任何生命周期价值，但企业应非常谨慎地为这些价值建立适当的分类法。

该字段的当前常用值为

实验性"(experimental)--实验性或早期的、非生产性组件，表明用户可能不喜欢使用它，而喜欢使用其他更成熟的组件，或表明可靠性保证较低或没有保证 * "生产性"(production)--成熟的、自有的、受维护的组件 * "废弃的"(deprecated)--处于生命周期末期的组件，可能会在以后某个时间点消失

`spec.Owner` [必填]

一个实体参考给组件的 Owner，例如artist-relations-team该字段为必填字段。

在 Backstage 中，一个组件的 Owner 是对该组件负最终责任的唯一实体(通常是一个团队)，它拥有开发和维护该组件的权力和能力。如果出现问题或需要功能，他们将是联系人。该字段的主要用途是在 Backstage 中显示，以便查看目录项的人了解该组件属于谁。它不能用于自动化流程，例如在运行时系统中分配授权。可能还有其他人也开发或以其他方式接触该组件，但最终的所有者始终只有一个。

|种类| 默认值名称空间| 生成联系类型 | | ------------------------------------------------------ | | ------------------------------------------ | ------------------------------------------------------------------------------- | | |组(默认)、用户| 与本实体相同，通常default|所有者|

`spec.system` [可选]

一个实体参考组件所属的系统，例如artist-engagement-portal该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | ----------------------------------------------------------------------------- | | |系统(默认) | 与本实体相同，通常为default|部分|

`spec.subcomponentOf` [可选]

一个实体参考与该组件所属的另一个组件连接，例如spotify-ios-app该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | ---------------------------------------- | | ------------------------------------------ | ----------------------------------------------------------------------------- | | |组件(默认) | 与本实体相同，通常为default|部分|

`spec.providesApis` [可选]

的数组实体引用组件提供的应用程序接口，例如artist-api该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | | |API(默认) | 与本实体相同，通常为default|提供应用程序|

`spec.consumesApis` [可选]

的数组实体引用到组件使用的应用程序接口，例如artist-api该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | | |API(默认) | 与本实体相同，通常为default|消耗应用程序|

`spec.dependsOn` [可选]

的数组实体引用组件所依赖的组件和资源，例如artists-db该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | --------------------------------------------------------------------------------------------- | | |组件| 与本实体相同，通常default|取决于| |资源| 与本实体相同，通常default|取决于|

类型：模板

下面介绍以下实体种类：

| 域 | 值 | | ------------ | ---------------------- | | |apiVersion|backstage.io/v1beta2| |kind|Template|

模板定义既描述了在脚手架向导前端部分呈现的参数，也描述了在脚手架化该组件时执行的步骤。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1beta2
kind: Template
# some metadata about the template itself
metadata:
  name: v1beta2-demo
  title: Test Action template
  description: scaffolder v1beta2 template demo
spec:
  owner: backstage/techdocs-core
  type: service

  # these are the steps which are rendered in the frontend with the form input
  parameters:
    - title: Fill in some steps
      required:
        - name
      properties:
        name:
          title: Name
          type: string
          description: Unique name of the component
          ui:autofocus: true
          ui:options:
            rows: 5
    - title: Choose a location
      required:
        - repoUrl
      properties:
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com

  # here's the steps that are executed in series in the scaffolder backend
  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      input:
        url: ./template
        values:
          name: '{{ parameters.name }}'

    - id: fetch-docs
      name: Fetch Docs
      action: fetch:plain
      input:
        targetPath: ./community
        url: https://github.com/backstage/community/tree/main/backstage-community-sessions

    - id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: ['github.com']
        description: 'This is {{ parameters.name }}'
        repoUrl: '{{ parameters.repoUrl }}'

    - id: register
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: {{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: '/catalog-info.yaml'

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1beta2和Template分别为

`metadata.tags` [可选]

可与模板关联的字符串列表，例如['recommended', 'react'].

该列表也将用于在前端显示给用户，因此您可以通过这些标签搜索和分组模板。

`spec.type` [必填]

模板创建的组件类型，例如website用于筛选模板，最好与组件规格类型由模板创建。

`spec.parameters` [必填]

您可以进一步了解parameters密钥这里

`spec.steps` [必填]

您可以进一步了解steps密钥这里

`spec.owner` [可选]

一个实体参考给模板的 Owner，例如artist-relations-team该字段为必填字段。

在 Backstage 中，模板的 Owner 是对模板负最终责任的唯一实体(通常是一个团队)，拥有开发和维护模板的权力和能力。如果出现问题或需要功能，他们将是联系人。该字段的主要用途是在 Backstage 中显示，以便查看目录项的人了解该模板属于谁。该字段不用于自动化流程，例如在运行时系统中分配授权。可能还有其他人也开发或以其他方式接触该模板，但最终的所有者始终只有一个。

Kind: API

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|API|

应用程序接口描述了组件可以公开的接口。应用程序接口可以用不同的格式定义，如OpenAPI,AsyncAPI,图形QL,gRPC或其他格式。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: artist-api
  description: Retrieve artist details
spec:
  type: openapi
  lifecycle: production
  owner: artist-relations-team
  system: artist-engagement-portal
  definition: |
    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Artist API
      license:
        name: MIT
    servers:
      - url: http://artist.spotify.net/v1
    paths:
      /artists:
        get:
          summary: List all artists
    ...

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和API分别为

`spec.type` [必填]

以字符串形式表示的 API 定义类型，例如openapi该字段为必填字段。

软件目录接受任何类型值，但组织应非常谨慎地为这些类型建立适当的分类。包括 Backstage 本身在内的工具可能会读取该字段，并根据其值采取不同的行为。例如，OpenAPI 类型的 API 可能会使用 Backstage 界面中的 OpenAPI 查看器工具显示。

该字段的当前常用值为

openapi - 基于OpenAPI 版本 2 或版本 3 规范的 YAML 或 JSON 格式的 API 定义。 * asyncapi - 基于AsyncAPI 规范的 API 定义。 * graphql - 基于GraphQL schemas的 API 定义，用于消费基于GraphQL 的 API。 * grpc - 基于Protocol Buffers的 API 定义，与gRPC 一起使用。

`spec.lifecycle` [必填]

应用程序接口的生命周期状态，例如production该字段为必填字段。

软件目录可接受任何生命周期价值，但企业应非常谨慎地为这些价值建立适当的分类法。

该字段的当前常用值为

实验性"(experimental)--实验性或早期的、非生产性的应用程序接口，表明用户可能不喜欢使用它，而喜欢使用其他更成熟的应用程序接口，或表明可靠性保证较低或没有可靠性保证 * "生产性"(production)--成熟的、自有的、受维护的应用程序接口 * "废弃的"(deprecated)--处于生命周期末期的应用程序接口，可能会在以后某个时间点消失

`spec.Owner` [必填]

一个实体参考给组件的 Owner，例如artist-relations-team该字段为必填字段。

在 Backstage 中，API 的所有者是对 API 负有最终责任的单个实体(通常是一个团队)，他们拥有开发和维护 API 的权力和能力。如果出现问题或需要功能，他们将是联系人。该字段的主要用途是在 Backstage 中显示，以便查看目录项的人了解该 API 属于谁。该字段不用于自动化流程，例如在运行时系统中分配授权。可能还有其他人也开发或以其他方式接触 API，但最终所有者始终只有一个。

`spec.system` [可选]

一个实体参考的系统，例如artist-engagement-portal该字段为可选字段。

`spec.definition` [必填]

应用程序接口的定义基于spec.type该字段为必填字段。

种类：组

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|Group|

小组描述了一个组织实体，例如一个团队、一个业务单位或一个兴趣小组中的松散人员集合。这些小组的成员在目录中被模拟为以下类型用户.

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: infrastructure
  description: The infra business unit
spec:
  type: business-unit
  profile:
    displayName: Infrastructure
    email: [email protected]
    picture: https://example.com/groups/bu-infrastructure.jpeg
  parent: ops
  children: [backstage, other]
  members: [jdoe]

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和Group分别为

`spec.type` [必填]

以字符串形式表示的组类型，例如team目前，该字段没有强制规定的值集，因此由采用组织选择符合其组织层次结构的术语。

该字段的一些常见值可以是

team * business-unit * product-area * root - 如果需要，作为层次结构的共同虚拟根

`spec.profile` [可选]

小组的可选配置文件信息，主要用于显示目的。该结构的所有字段也都是可选的。电子邮件将是某种形式的小组电子邮件，该小组可能希望使用该电子邮件与他们联系。图片预计是一个 URL，指向代表该小组的图片，浏览器可以获取该图片并将其显示在小组页面或类似页面上。

`spec.parent` [可选]

层次结构中的直接父组(如果有)。并非所有组都必须有一个父组；目录支持多根层次结构。但是，组不能有一个以上的父组。

该字段是实体参考.

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | --------------------------------------------------------------------------------- | | |组(默认) | 与本实体相同，通常为default|childOf|

`spec.children` [必填]

该组在层次结构中的直接子组(其parent列表必须存在，但如果没有子组，则可能为空。项目不保证以任何特定方式排序。

该数组的条目如下实体引用.

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | --------------------------------------------------------------------------------- | | |组(默认) | 与本实体相同，通常为default|parentOf|

`spec.members` [可选]

作为该组直接成员的用户。项目不保证以任何特定方式排序。

该数组的条目如下实体引用.

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | ------------------------------------------------------------------------------------- | | |用户(默认) | 与本实体相同，通常为default|有成员|

类型：用户

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|User|

用户指的是一个人，如雇员、承包商或类似人员。用户属于组目录中的实体。

这些目录用户条目与 Backstage 生态系统内的身份验证工作方式有关。请参见授权文档中有关这些概念的讨论。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: jdoe
spec:
  profile:
    displayName: Jenny Doe
    email: jenny-[email protected]
    picture: https://example.com/staff/jenny-with-party-hat.jpeg
  memberOf: [team-b, employees]

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和User分别为

`spec.profile` [可选]

用户的可选个人资料信息，主要用于显示目的。该结构的所有字段也都是可选的。电子邮件将是某种形式的主要电子邮件，用户可能希望用它来与自己联系。图片预计是一个 URL，指向一张能代表用户的图片，浏览器可以获取并在个人资料页面或类似页面上显示该图片。

`spec.memberOf` [必填]

用户是直接成员的群组列表(即此处不列出传递成员)。该列表必须存在，但如果用户不是任何群组的成员，则可能为空。项目不保证以任何特定方式排序。

该数组的条目如下实体引用.

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | ------------------------------------------------------------------------------------- | | |组(默认) | 与本实体相同，通常为default|成员|

类型：资源

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|Resource|

资源描述了系统运行所需的基础设施，如 BigTable 数据库、Pub/Sub 主题、S3 buckets 或 CDN。将它们与组件和系统一起建模，可以可视化资源占用情况，并围绕它们创建工具。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: artists-db
  description: Stores artist details
spec:
  type: database
  owner: artist-relations-team
  system: artist-engagement-portal

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和Resource分别为

`spec.Owner` [必填]

一个实体参考给资源的 Owner，例如artist-relations-team该字段为必填字段。

在 Backstage 中，资源的 Owner 是对资源负最终责任的唯一实体(通常是一个团队)，他们拥有开发和维护资源的权力和能力。如果出现问题或需要功能，他们将是联系人。该字段的主要用途是在 Backstage 中显示，以便查看目录项的人了解该资源属于谁。该字段不用于自动化流程，例如在运行时系统中分配授权。可能还有其他人也管理或以其他方式接触该资源，但最终的所有者始终只有一个。

`spec.type` [必填]

资源类型字符串，例如database该字段为必填字段，目前没有强制规定该字段的值集，因此采用组织可自行选择与其技术栈中使用的资源相匹配的术语。

该字段的一些常见值可以是

数据库

`spec.system` [可选]

一个实体参考资源所属的系统，例如artist-engagement-portal该字段为可选字段。

`spec.dependsOn` [可选]

的数组实体引用到该资源所依赖的组件和资源，例如artist-lookup该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | --------------------------------------------------------------------------------------------- | | |组件| 与本实体相同，通常default|取决于| |资源| 与本实体相同，通常default|取决于|

`spec.dependencyOf` [可选]

的数组实体引用的组件和资源，例如artist-lookup该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | --------------------------------------------------------------------------------------------- | | |组件| 与本实体相同，通常default|dependencyOf| |资源| 与本实体相同，通常default|dependencyOf|

类型：系统

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|System|

系统是资源和组件的集合。系统可能会公开或使用一个或多个应用程序接口(API)。它被视为一个抽象层，可让潜在用户深入了解公开的功能，而无需过多了解所有组件的细节。这也为拥有团队提供了决定已发布工件和应用程序接口的可能性。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: artist-engagement-portal
  description: Handy tools to keep artists in the loop
spec:
  owner: artist-relations-team
  domain: artists

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和System分别为

`spec.Owner` [必填]

一个实体参考给系统的 Owner，例如artist-relations-team该字段为必填字段。

在 Backstage 中，系统的 Ownner 是对系统负最终责任的单个实体(通常是一个团队)，他们拥有开发和维护系统的权力和能力。如果出现问题或需要功能，他们将是联系人。该字段的主要用途是在 Backstage 中显示，以便查看目录项的人了解该系统属于谁。该字段不用于自动化流程，例如在运行时系统中分配授权。可能还有其他人也开发或以其他方式接触该系统，但最终的所有者始终只有一个。

`spec.domain` [可选]

一个实体参考系统所属的域，例如artists该字段为可选字段。

|种类| 默认值名称空间| 生成联系类型 | | --------------------------------------- | | ------------------------------------------ | ----------------------------------------------------------------------------- | | |域名(默认) | 与本实体相同，通常为default|部分|

类型：域

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|Domain|

领域是指共享术语、领域模型、业务目的或文档的系统集合，即形成一个有边界的上下文。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: artists
  description: Everything about artists
spec:
  owner: artist-relations-team

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和Domain分别为

`spec.Owner` [必填]

一个实体参考给域的 Owner，例如artist-relations-team该字段为必填字段。

在 Backstage 中，域的 Owner 是对域负最终责任的唯一实体(通常是一个团队)，他们拥有开发和维护域的权力和能力。如果出现问题或需要功能，他们将是联系人。该字段的主要用途是在 Backstage 中显示，以便查看目录项的人了解该域属于谁。该字段不用于自动化流程，例如在运行时系统中分配授权。可能还有其他人也开发或以其他方式接触该域，但最终的所有者始终只有一个。

Kind: Location

描述以下实体种类：

| 域 | 值 | | ------------ | ----------------------- | | |apiVersion|backstage.io/v1alpha1| |kind|Location|

位置是一个标记，用于引用其他可查找目录数据的地方。

这种类型的描述符文件可能如下所示。

apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: org-data
spec:
  type: url
  targets:
    - http://github.com/myorg/myproject/org-data-dump/catalog-info-staff.yaml
    - http://github.com/myorg/myproject/org-data-dump/catalog-info-consultants.yaml

除了通用信封元数据这种形状的结构如下

`apiVersion` 和 `kind` [必填]

恰好等于backstage.io/v1alpha1和Location分别为

`spec` [必填]

spec最小规格应为空对象。

`spec.type` [可选]

单个位置类型，该类型在规范中指定的目标中是通用的。如果省略，则会从最初读取实体数据的位置类型中继承。例如，如果您有一个url类型的位置，读取后会产生Location类实体，没有spec.type则实体中的引用目标也将隐式地属于url这很有用，因为你可以使用相对目标路径(见下文)在目录结构中定义事物的层次结构，而且无论从本地磁盘上的file位置，或上载到 VCS。

`spec.target` [可选]

单个目标字符串，可以是绝对路径/URL(取决于类型)，也可以是相对路径，如./details/catalog-info.yaml相对于该位置实体本身的位置进行解析。

`spec.targets` [可选]

目标字符串列表，可以是绝对路径/URL(取决于类型)，也可以是相对路径，如./details/catalog-info.yaml相对于该位置实体本身的位置进行解析。

`spec.presence` [可选]

描述位置的目标是否需要存在。默认为'required'如果未指定，也可以是'optional'.

内容
实体的整体形状
- 描述符格式中的替换
所有种类的共同点：信封
所有类型的共同点：元数据
所有种类的共同点：关系
所有类型的共同点：状态
类型：组件
类型：模板
Kind: API
种类：组
类型：用户
类型：资源
类型：系统
类型：域
- apiVersion 和 kind [必填]
- spec.Owner [必填]
Kind: Location

内容​

实体的整体形状​

描述符格式中的替换​

所有种类的共同点：信封​

apiVersion 和 kind [必填]​

metadata [必填]​

spec [varies] [不同]​

所有类型的共同点：元数据​

name [必填]​

namespace [可选]​

uid [输出]​

title [可选]​

description [可选]​

labels [可选]​

annotations [可选]​

tags [可选]​

links [可选]​

所有种类的共同点：关系​

所有类型的共同点：状态​

类型：组件​

apiVersion 和 kind [必填]​

spec.type [必填]​

spec.lifecycle [必填]​

spec.Owner [必填]​

spec.system [可选]​

spec.subcomponentOf [可选]​

spec.providesApis [可选]​

spec.consumesApis [可选]​

spec.dependsOn [可选]​

类型：模板​

apiVersion 和 kind [必填]​

metadata.tags [可选]​

spec.type [必填]​

spec.parameters [必填]​

spec.steps [必填]​

spec.owner [可选]​

Kind: API​

apiVersion 和 kind [必填]​

spec.type [必填]​

spec.lifecycle [必填]​

spec.Owner [必填]​

spec.system [可选]​

spec.definition [必填]​

种类：组​

apiVersion 和 kind [必填]​

spec.type [必填]​

spec.profile [可选]​

spec.parent [可选]​

spec.children [必填]​

spec.members [可选]​

类型：用户​

apiVersion 和 kind [必填]​

spec.profile [可选]​

spec.memberOf [必填]​

类型：资源​

apiVersion 和 kind [必填]​

spec.Owner [必填]​

spec.type [必填]​

spec.system [可选]​

spec.dependsOn [可选]​

spec.dependencyOf [可选]​

类型：系统​

apiVersion 和 kind [必填]​

spec.Owner [必填]​

spec.domain [可选]​

类型：域​

apiVersion 和 kind [必填]​

spec.Owner [必填]​

Kind: Location​

apiVersion 和 kind [必填]​

spec [必填]​

spec.type [可选]​

spec.target [可选]​

spec.targets [可选]​

spec.presence [可选]​

内容

实体的整体形状

描述符格式中的替换

所有种类的共同点：信封

`apiVersion` 和 `kind` [必填]

`metadata` [必填]

`spec` [varies] [不同]

所有类型的共同点：元数据

`name` [必填]

`namespace` [可选]

`uid` [输出]

`title` [可选]

`description` [可选]

`labels` [可选]

`annotations` [可选]

`tags` [可选]

`links` [可选]

所有种类的共同点：关系

所有类型的共同点：状态

类型：组件

`apiVersion` 和 `kind` [必填]

`spec.type` [必填]

`spec.lifecycle` [必填]

`spec.Owner` [必填]

`spec.system` [可选]

`spec.subcomponentOf` [可选]

`spec.providesApis` [可选]

`spec.consumesApis` [可选]

`spec.dependsOn` [可选]

类型：模板

`apiVersion` 和 `kind` [必填]

`metadata.tags` [可选]

`spec.type` [必填]

`spec.parameters` [必填]

`spec.steps` [必填]

`spec.owner` [可选]

Kind: API

`apiVersion` 和 `kind` [必填]

`spec.type` [必填]

`spec.lifecycle` [必填]

`spec.Owner` [必填]

`spec.system` [可选]

`spec.definition` [必填]

种类：组

`apiVersion` 和 `kind` [必填]

`spec.type` [必填]

`spec.profile` [可选]

`spec.parent` [可选]

`spec.children` [必填]

`spec.members` [可选]

类型：用户

`apiVersion` 和 `kind` [必填]

`spec.profile` [可选]

`spec.memberOf` [必填]

类型：资源

`apiVersion` 和 `kind` [必填]

`spec.Owner` [必填]

`spec.type` [必填]

`spec.system` [可选]

`spec.dependsOn` [可选]

`spec.dependencyOf` [可选]

类型：系统

`apiVersion` 和 `kind` [必填]

`spec.Owner` [必填]

`spec.domain` [可选]

类型：域

`apiVersion` 和 `kind` [必填]

`spec.Owner` [必填]

Kind: Location

`apiVersion` 和 `kind` [必填]

`spec` [必填]

`spec.type` [可选]

`spec.target` [可选]

`spec.targets` [可选]

`spec.presence` [可选]