소프트웨어 카탈로그 엔티티 작성

목표

Backstage 소프트웨어 카탈로그의 엔티티 여덟 종류를 직접 작성하고, 그 사이의 관계 선언과 참조 형식을 손에 익힙니다. 마지막에는 같은 소유권 정보를 실제 클러스터 워크로드에 표현해 두 세계를 연결합니다.

왜 중요한가

카탈로그는 목록이 아니라 관계 그래프입니다. spec.owner, spec.system, spec.providesApis 를 한쪽에만 선언하면 카탈로그가 양방향 관계를 계산해 줍니다 — 그래서 어떤 필드를 어디에 쓰느냐가 곧 그래프의 모양을 결정합니다. 특히 소유자는 카탈로그에서 딱 하나만 정확해야 한다면 그것일 만큼 중요합니다. 장애 호출, 취약점 티켓, 비용 귀속, 폐기 결정이 전부 소유자에서 갈리기 때문입니다. 그리고 소유자는 반드시 사람이 아니라 팀이어야 합니다 — 사람은 퇴사하고 팀은 인수되기 때문입니다. 이 실습에서 만든 파일은 실제 운영에서는 서비스 코드 저장소 루트에 함께 커밋되어 디스커버리로 자동 등록됩니다. Backstage 자체는 이 환경에 없으므로 채점은 파일과 클러스터 오브젝트를 읽어서 합니다.

단계

1. /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.
2. /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 으로 시작하는 여러 줄 문자열(블록 스칼라).
3. /root/cba-catalog/resource-db.yaml 에 Resource 를 작성하세요 — kind: Resource, metadata.name: checkout-db, spec.type: database, spec.owner: group:team-checkout, spec.system: commerce.
4. /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.
5. /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.
6. /root/cba-catalog/all.yaml 에 Location 을 작성하세요 — kind: Location, metadata.name: cba-catalog-all, spec.type: url, spec.targets 에 앞에서 만든 엔티티 파일 일곱 개를 ./catalog-info.yaml 처럼 상대 경로로 나열(총 7 개).
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, 그리고 파드 템플릿 라벨에도 backstage.io/kubernetes-id: checkout-service 를 넣으세요. 이미지는 nginx:1.27-alpine, replicas 는 1 입니다.
8. /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: providesApis 를 API 쪽에도 반대로 적으려는 것. 관계는 한쪽 선언으로 카탈로그가 양방향으로 계산합니다.
• 흔한 실수 3: backstage.io/kubernetes-id 를 엔티티에는 라벨로, 워크로드에는 애너테이션으로 넣는 것. 방향이 반대입니다 — 엔티티에는 애너테이션, 워크로드에는 라벨입니다.

단계 8개

1. Component 엔티티
2. API 엔티티
3. Resource 엔티티
4. System 과 Domain
5. Group 과 User
6. Location 으로 묶기
7. 같은 소유권을 클러스터 라벨로
8. 엔티티 참조 정규화