ソフトウェアカタログのエンティティ作成

한국어 원문으로 표시합니다.

목표

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, 그리고 파드 템플릿 라벨에도 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: providesApis 를 API 쪽에도 반대로 적으려는 것. 관계는 한쪽 선언으로 카탈로그가 양방향으로 계산합니다.
흔한 실수 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, 그리고 파드 템플릿 라벨에도 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 를 소문자로, 네임스페이스를 생략하지 않고 씁니다. 앞에서 만든 모든 엔티티가 대상입니다.