Skip to main content

ADR002默认软件目录文件格式

背景​

Backstage 自带软件目录功能，你可以用它来跟踪所有软件组件和更多内容。 它可以利用各种来源的数据，其中一个软件包包含了一个自定义的数据库支持目录。 它能够根据你所选择的版本控制系统中的小描述文件的内容自动更新。 开发人员创建这些文件并与他们的代码一起维护，目录系统会做出相应的反应。

本 ADR 描述了这些描述符文件的默认格式。

灵感​

Spotify 内部大量使用自制的软件目录系统，该系统是 Backstage 和其他重要基础架构的核心部分。 该目录的用户体验、经验和某些元数据将被移植到开源工作中。

这里描述的文件格式也从kubernetes 对象格式.

核心概念​

有许多描述符文件，它们的所有位置(例如在版本控制系统中)都会在软件目录中注册。 注册方法不在本文讨论范围内；注册可以在Backstage手动进行，也可以通过 CI/CD 管道的推送事件或版本控制系统的 Webhook 触发器等方式进行。

每个文件按照Backstage系统模型所有这些实体都有一个共同的结构和术语，它们都存储在软件目录中，然后可以从目录中进行查询。

实体有不同的名称，它们可以通过这些名称相互引用。

格式​

描述符文件使用YAML每个文件可以由多个 YAML 文档组成(用"...... "分隔)。---)，其中每个文档描述一个实体。

这是一个实体定义示例，其中包含一些模拟数据。

---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: frobs-awesome
  description: |
    Backend service that implements the Frobs API, as defined
    in [the Frobs RFC](https://example.com/spec/frob.html).
  labels:
    system: frobs
    lifecycle: production
    example.com/service-discovery-name: frobsawesome
  annotations:
    circleci.com/project-slug: github/example-org/frobs-awesome
spec:
  type: service

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

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

信封​

根信封对象的结构如下

###apiVersion 和kind。

kind是描述的高级实体类型，通常来自Backstage系统模型目录的最初版本将侧重于Component一种

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

Backstage特定实体有一个apiVersion的backstage.io/在将这些规范与 kubernetes 对象清单等共同托管时，这一点可能很重要。

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

metadata​

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

spec​

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

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

元数据​

metadata根字段的嵌套结构如下

name​

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

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

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

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

例如visits-tracking-service,CircleciBuildsDs_avro_gcs

`名称空间​

name该字段是可选的，目前除了在指定时约束名称唯一性之外，没有其他特殊语义。 该字段保留给将来使用，可能会有更广泛的语义含义。

命名空间也可以是目录的一部分，它们是v1/Namespace实体，即不是针对 Backstage，而是与 Kubernetes 中的实体相同。

description​

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

`标签​

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

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

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

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

backstage.io/前缀保留给Backstage核心组件使用。 有些键，如system也有预定义的语义。

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

`注释​

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

它们的作用主要是(但不限于)引用到外部系统，例如引用到实体被摄取的 git ref，引用到监控和日志系统，引用到 pagerduty schedules 等。

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

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

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

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

组件​

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

spec该类型的对象如下：

字段 | 类型 | 必填 | 说明 | | ------ | ------ | -------- | -------------------------------------- | | | |type| 字符串 | 是 | 组件类型，例如service. |