编写软件目录实体

目标

亲手编写 Backstage 软件目录中的八种实体，熟悉实体之间的关系声明与引用格式。最后，把同一份所有权信息呈现在真实的集群工作负载中，连接这两个世界。

为什么重要

目录不是清单，而是关系图。只需在一侧声明 spec.owner、spec.system、spec.providesApis，目录就会计算双向关系——因此，字段写在哪里会直接决定关系图的形态。如果目录中只能保证一项信息准确，那就应当是所有者。事故呼叫、漏洞工单、成本归属和废弃决策，全都由所有者决定。并且所有者必须是团队，而不是个人——人员会离职，团队则会被承接。本实验中创建的文件在实际运行环境中会与服务代码一起提交到仓库根目录，并通过发现机制自动注册。本环境中没有 Backstage，因此评分会读取文件和集群对象。

步骤

在 /root/cba-catalog/catalog-info.yaml 中编写 Component——apiVersion: backstage.io/v1alpha1、kind: Component、metadata.name: checkout-service、metadata.description 可填写任意句子；在 metadata.annotations 中加入 backstage.io/techdocs-ref: dir:. 和 backstage.io/kubernetes-id: checkout-service；设置 spec.type: service、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce，并让 spec.providesApis 的第一项为 checkout-api。
在 /root/cba-catalog/api-checkout.yaml 中编写 API——kind: API、metadata.name: checkout-api、spec.type: openapi、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce，并在 spec.definition 中写入以 openapi: 3.0.0 开头的多行字符串（块标量）。
在 /root/cba-catalog/resource-db.yaml 中编写 Resource——kind: Resource、metadata.name: checkout-db、spec.type: database、spec.owner: group:team-checkout、spec.system: commerce。
在 /root/cba-catalog/system-commerce.yaml 中编写 System——kind: System、metadata.name: commerce、spec.owner: group:team-checkout、spec.domain: retail。在 /root/cba-catalog/domain-retail.yaml 中编写 Domain——kind: Domain、metadata.name: retail、spec.owner: group:team-checkout。
在 /root/cba-catalog/group-team-checkout.yaml 中编写 Group——kind: Group、metadata.name: team-checkout、spec.type: team、spec.profile.displayName 可填写任意值、spec.children: []。在 /root/cba-catalog/user-youngju.yaml 中编写 User——kind: User、metadata.name: youngju，并让 spec.memberOf 的第一项为 team-checkout。
在 /root/cba-catalog/all.yaml 中编写 Location——kind: Location、metadata.name: cba-catalog-all、spec.type: url，在 spec.targets 中用 ./catalog-info.yaml 这样的相对路径列出之前创建的七个实体文件（共 7 个）。
在集群中表示相同的所有权信息。创建命名空间 cba-commerce（标签为 app.kubernetes.io/part-of: commerce），并在其中创建 Deployment checkout-service——在元数据标签中加入 backstage.io/kubernetes-id: checkout-service、app.kubernetes.io/name: checkout-service、app.kubernetes.io/part-of: commerce，在 Pod 模板标签中也加入 backstage.io/kubernetes-id: checkout-service。镜像使用 nginx:1.27-alpine，replicas 为 1。
在 /root/cba-catalog/refs.txt 中逐行写入之前创建的所有实体（Component、API、Resource、System、Domain、Group、User——共 7 个）的规范化引用。格式为 <소문자 kind>:default/<이름>。例如：component:default/checkout-service。不包含 Location。

参考

实体引用格式为 [<kind>:][<namespace>/]<name>，命名空间默认值为 default。
多行字符串使用 YAML 块标量（|）保存。
常见错误 1：把 spec.owner 写成人名。人员会离开，团队会保留下来。
常见错误 2：试图在 API 一侧反向填写 providesApis。只需在一侧声明，目录就会计算双向关系。
常见错误 3：在实体中把 backstage.io/kubernetes-id 写成标签，却在工作负载中写成注解。方向正好相反——实体中使用注解，工作负载中使用标签。

Component 实体

在 /root/cba-catalog/catalog-info.yaml 中编写 Component——apiVersion: backstage.io/v1alpha1、kind: Component、metadata.name: checkout-service、metadata.description 可填写任意句子；在 metadata.annotations 中加入 backstage.io/techdocs-ref: dir:. 和 backstage.io/kubernetes-id: checkout-service；设置 spec.type: service、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce，并让 spec.providesApis 的第一项为 checkout-api。

Component 的必需 spec 是 type、lifecycle 和 owner。所有者应指向团队而不是个人，并明确写出引用格式的前缀。

API 实体

在 /root/cba-catalog/api-checkout.yaml 中编写 API——kind: API、metadata.name: checkout-api、spec.type: openapi、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce，并在 spec.definition 中写入以 openapi: 3.0.0 开头的多行字符串（块标量）。

API 实体将定义（definition）保存为字符串。使用 YAML 块标量可以原样保存多行内容。

Resource 实体

在 /root/cba-catalog/resource-db.yaml 中编写 Resource——kind: Resource、metadata.name: checkout-db、spec.type: database、spec.owner: group:team-checkout、spec.system: commerce。

Resource 是组件所需的基础设施。表示种类的字段名与 Component 相同。

System 与 Domain

在 /root/cba-catalog/system-commerce.yaml 中编写 System——kind: System、metadata.name: commerce、spec.owner: group:team-checkout、spec.domain: retail。在 /root/cba-catalog/domain-retail.yaml 中编写 Domain——kind: Domain、metadata.name: retail、spec.owner: group:team-checkout。

System 是一组协同工作的对象，Domain 是多个系统的上层领域。连接两者的字段位于 System 一侧。

Group 与 User

在 /root/cba-catalog/group-team-checkout.yaml 中编写 Group——kind: Group、metadata.name: team-checkout、spec.type: team、spec.profile.displayName 可填写任意值、spec.children: []。在 /root/cba-catalog/user-youngju.yaml 中编写 User——kind: User、metadata.name: youngju，并让 spec.memberOf 的第一项为 team-checkout。

Group 代表团队，User 代表个人。表示个人所属团队的字段位于 User 一侧。

用 Location 汇总

在 /root/cba-catalog/all.yaml 中编写 Location——kind: Location、metadata.name: cba-catalog-all、spec.type: url，在 spec.targets 中用 ./catalog-info.yaml 这样的相对路径列出之前创建的七个实体文件（共 7 个）。

Location 是指向其他实体文件的路标。只有被指向的目标真实存在时，它才有意义。

用集群标签表示相同的所有权

在集群中表示相同的所有权信息。创建命名空间 cba-commerce（标签为 app.kubernetes.io/part-of: commerce），并在其中创建 Deployment checkout-service——在元数据标签中加入 backstage.io/kubernetes-id: checkout-service、app.kubernetes.io/name: checkout-service、app.kubernetes.io/part-of: commerce，在 Pod 模板标签中也加入 backstage.io/kubernetes-id: checkout-service。镜像使用 nginx:1.27-alpine，replicas 为 1。

Kubernetes 插件会查找标签值与实体注解值相同的工作负载。请分清实体使用注解、工作负载使用标签。

规范化实体引用

在 /root/cba-catalog/refs.txt 中逐行写入之前创建的所有实体（Component、API、Resource、System、Domain、Group、User——共 7 个）的规范化引用。格式为 <소문자 kind>:default/<이름>。例如：component:default/checkout-service。不包含 Location。

规范化格式中，kind 使用小写，并且不能省略命名空间。之前创建的所有实体都是目标。