LabHub
배우기 러닝패스 코스

CBA — Backstage認定アソシエイト

カタログの整合性診断とゲート

LabHub 에서 이어서 보기

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

목표

인계받은 카탈로그를 정적으로 진단해 결함 네 종류를 찾아내고, 고친 사본을 만들고, 같은 검사를 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/ 안의 엔티티 파일 개수입니다.

참고

인계받은 카탈로그 재현

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

지시문에 적힌 그대로 옮기세요. 빠져 있다고 적힌 필드는 채우지 말아야 합니다. 그 결함이 뒤 단계에서 진단할 대상입니다.

필수 필드 누락 진단

/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 이 더해집니다.

필수 필드는 kind 마다 다릅니다. Component 와 API 는 type, lifecycle, owner 셋이 모두 필요하고 Resource 는 둘, System 과 Domain 은 owner 하나입니다.

끊어진 소유자 진단

/root/cba-audit/dangling-owners.txt 에 spec.owner 가 이 디렉터리에 없는 그룹을 가리키는 경우를 적으세요. 형식은 <엔티티 참조> <정규화한 소유자 참조> 입니다. 소유자의 기본 kind 는 group, 네임스페이스 기본값은 default 입니다.

소유자 값은 kind 를 생략할 수 있으므로 비교하기 전에 정규화해야 합니다. 네임스페이스의 기본값은 default 입니다.

끊어진 참조 진단

/root/cba-audit/dangling-refs.txt 에 소유자를 뺀 나머지 참조가 없는 대상을 가리키는 경우를 적으세요. 대상 필드는 spec.system(기본 kind system), spec.domain(domain), spec.dependsOn(component), spec.providesApis(api) 입니다. 형식은 <가리킨 쪽 참조> <없는 대상의 참조> 입니다.

소유자 말고도 대상을 가리키는 필드가 넷 더 있습니다. 각 필드마다 기본 kind 가 다르므로 정규화할 때 그것을 맞춰야 합니다.

의존 순환 진단

/root/cba-audit/dependency-cycle.txt 에 spec.dependsOn 간선을 따라갔을 때 순환에 걸리는 엔티티의 참조를 한 줄에 하나씩 적으세요. 실제로 존재하는 엔티티를 가리키는 간선만 셉니다.

dependsOn 만 따라가면 됩니다. 실제로 존재하는 엔티티를 가리키는 간선만 세고, 그 위에서 자기 자신으로 돌아오는 길이 있는 엔티티를 찾으세요.

고친 카탈로그

/root/cba-audit/fixed/ 에 고친 카탈로그를 만드세요. 2~5 단계의 네 가지 진단을 fixed/ 에 대해 다시 돌렸을 때 전부 0 건이어야 하고, incoming/ 에 있던 여덟 엔티티는 kind 와 이름 그대로 모두 남아 있어야 합니다. 필요하면 없는 엔티티를 새로 만들어도 됩니다.

조직 데이터를 먼저 채우고 그다음 묶음, 마지막에 개별 엔티티를 고치세요. 결함이 있는 엔티티를 지워서 목록을 깨끗하게 만드는 것은 고친 것이 아닙니다.

PR 에서 도는 lint 게이트

/root/cba-audit/lint.sh 를 작성하세요. 첫 번째 인자로 받은 디렉터리를 검사해서, 필수 필드 누락이나 없는 대상을 가리키는 참조가 하나라도 있으면 0 이 아닌 값으로, 아무것도 없으면 0 으로 끝나야 합니다. 채점기는 이 스크립트를 incoming/, fixed/, 그리고 결함을 하나씩 심은 디렉터리 두 개에 대해 실행합니다.

게이트는 깨끗한 입력에서 0 을 내는 것만으로는 부족합니다. 결함을 일부러 넣어 보고 0 이 아닌 값이 나오는지 반드시 확인하세요. 채점기도 그렇게 시험합니다.

감사 결과를 클러스터에

감사 결과를 클러스터에 남기세요. 네임스페이스 cba-audit 를 만들고(라벨 app.kubernetes.io/part-of: developer-portal), 그 안에 ConfigMap catalog-audit 을 만드세요. 키는 셋입니다 — incoming-findings 는 2~5 단계에서 찾은 결함의 총 건수, fixed-findings 는 0, entities 는 fixed/ 안의 엔티티 파일 개수입니다.

숫자를 손으로 세지 말고 앞 단계의 산출물에서 계산해 넣으세요. 채점기는 원본 디렉터리에서 같은 값을 다시 계산해 대조합니다.