카탈로그 정합성 진단과 게이트

목표

인계받은 카탈로그를 정적으로 진단해 결함 네 종류를 찾아내고, 고친 사본을 만들고, 같은 검사를 PR 에서 돌릴 lint 게이트로 굳힙니다. Backstage 는 이 환경에 없으므로 모든 진단은 파일을 읽어서 합니다.

왜 중요한가

카탈로그는 등록되는 순간이 아니라 시간이 지나면서 썩습니다. 그리고 썩음의 대부분은 Backstage 가 오류로 알려 주지 않습니다. 스키마를 어긴 엔티티는 표시되지만, 없는 대상을 가리키는 참조는 그냥 관계가 계산되지 않은 상태가 되어 화면에 빈 칸으로 나타납니다. 빈 화면은 장애처럼 보이지 않아서 아무도 신고하지 않고, 그래서 아무도 고치지 않습니다. 이 실습에서 다루는 네 가지가 실제 현장에서 반복해 나타나는 모양입니다. 특히 참조를 비교하기 전에 정규화하는 습관이 중요합니다. team-orders 와 group:team-orders 와 group:default/team-orders 는 같은 것을 가리키는데, 문자열로 비교하면 멀쩡한 참조가 결함으로 보고됩니다. 마지막 단계의 lint 게이트는 깨끗한 입력에서 0 이 나오는 것만 확인하면 반쪽입니다. 결함을 일부러 넣었을 때 0 이 아닌 값이 나와야 그 게이트가 무언가를 지키는 것입니다.

단계

1. /root/cba-audit/incoming/ 에 아래 여덟 개 파일을 그대로 만드세요. 모두 apiVersion: backstage.io/v1alpha1 입니다. 빠져 있다고 적힌 필드는 채우지 마세요.

• component-orders.yaml — Component orders-service, spec.type: service, spec.lifecycle: production, spec.owner: group:team-orders, spec.system: commerce-core, spec.providesApis 첫 항목 orders-api, spec.dependsOn 두 항목 resource:orders-db 와 component:ledger-service.
• component-ledger.yaml — Component ledger-service, spec.type: service, spec.lifecycle: production, spec.owner: group:team-ledger, spec.system: finance-core, spec.dependsOn 첫 항목 component:orders-service.
• component-report.yaml — Component report-worker, spec.type: service, spec.owner: group:team-analytics, spec.system: commerce-core, spec.dependsOn 첫 항목 resource:analytics-warehouse. spec.lifecycle 은 없습니다.
• api-orders.yaml — API orders-api, spec.type: openapi, spec.lifecycle: production, spec.system: commerce-core. spec.owner 는 없습니다.
• resource-orders-db.yaml — Resource orders-db, spec.type: database, spec.owner: group:team-storage, spec.system: commerce-core.
• system-commerce-core.yaml — System commerce-core, spec.owner: group:team-orders, spec.domain: retail-ops.
• group-team-orders.yaml — Group team-orders, spec.type: team.
• group-team-ledger.yaml — Group team-ledger, spec.type: team.

2. /root/cba-audit/missing-required.txt 에 필수 필드가 빠진 자리를 한 줄에 하나씩 적으세요. 형식은 <정규화된 엔티티 참조> <필드 경로> 입니다. 필수 필드는 모든 kind 공통으로 apiVersion, kind, metadata.name 이고, 여기에 Component 와 API 는 spec.type·spec.lifecycle·spec.owner, Resource 는 spec.type·spec.owner, System 과 Domain 은 spec.owner, Group 은 spec.type 이 더해집니다.
3. /root/cba-audit/dangling-owners.txt 에 spec.owner 가 이 디렉터리에 없는 그룹을 가리키는 경우를 적으세요. 형식은 <엔티티 참조> <정규화한 소유자 참조> 입니다. 소유자의 기본 kind 는 group, 네임스페이스 기본값은 default 입니다.
4. /root/cba-audit/dangling-refs.txt 에 소유자를 뺀 나머지 참조가 없는 대상을 가리키는 경우를 적으세요. 대상 필드는 spec.system(기본 kind system), spec.domain(domain), spec.dependsOn(component), spec.providesApis(api) 입니다. 형식은 <가리킨 쪽 참조> <없는 대상의 참조> 입니다.
5. /root/cba-audit/dependency-cycle.txt 에 spec.dependsOn 간선을 따라갔을 때 순환에 걸리는 엔티티의 참조를 한 줄에 하나씩 적으세요. 실제로 존재하는 엔티티를 가리키는 간선만 셉니다.
6. /root/cba-audit/fixed/ 에 고친 카탈로그를 만드세요. 2~5 단계의 네 가지 진단을 fixed/ 에 대해 다시 돌렸을 때 전부 0 건이어야 하고, incoming/ 에 있던 여덟 엔티티는 kind 와 이름 그대로 모두 남아 있어야 합니다. 필요하면 없는 엔티티를 새로 만들어도 됩니다.
7. /root/cba-audit/lint.sh 를 작성하세요. 첫 번째 인자로 받은 디렉터리를 검사해서, 필수 필드 누락이나 없는 대상을 가리키는 참조가 하나라도 있으면 0 이 아닌 값으로, 아무것도 없으면 0 으로 끝나야 합니다. 채점기는 이 스크립트를 incoming/, fixed/, 그리고 결함을 하나씩 심은 디렉터리 두 개에 대해 실행합니다.
8. 감사 결과를 클러스터에 남기세요. 네임스페이스 cba-audit 를 만들고(라벨 app.kubernetes.io/part-of: developer-portal), 그 안에 ConfigMap catalog-audit 을 만드세요. 키는 셋입니다 — incoming-findings 는 2~5 단계에서 찾은 결함의 총 건수, fixed-findings 는 0, entities 는 fixed/ 안의 엔티티 파일 개수입니다.

참고

• 참조는 [<kind>:][<namespace>/]<name> 이고 비교하기 전에 반드시 정규화합니다.
• 필드마다 기본 kind 가 다릅니다. spec.owner 는 group, spec.system 은 system, spec.dependsOn 은 component 입니다.
• 흔한 실수 1: 결함이 있는 엔티티를 지워서 목록을 깨끗하게 만드는 것. 안 보이게 만든 서비스도 새벽 세 시에는 깨집니다.
• 흔한 실수 2: 개별 엔티티부터 고치는 것. 없는 Group 과 Domain 을 먼저 만들지 않으면 같은 자리를 두 번 고치게 됩니다.
• 흔한 실수 3: lint 를 깨끗한 입력에서만 시험하는 것. 무조건 0 을 내는 게이트는 없는 것보다 나쁩니다.

단계 8개

1. 인계받은 카탈로그 재현
2. 필수 필드 누락 진단
3. 끊어진 소유자 진단
4. 끊어진 참조 진단
5. 의존 순환 진단
6. 고친 카탈로그
7. PR 에서 도는 lint 게이트
8. 감사 결과를 클러스터에