스키마가 통과해도 유효한 게 아니다

한 줄 요약

카탈로그는 스키마와 정책 두 층으로 거릅니다. 스키마만 통과한 엔티티는 형태만 맞을 뿐이라, 이름에 공백이 있어도 spec 을 오타로 써도 들어갑니다.

왜 두 층을 다 봐야 하나

앞 모듈에서 catalog-info.yaml 을 여러 개 썼습니다. 그런데 그 실습이 도는 곳에는 Backstage 백엔드가 없어서, 그 YAML 이 실제로 통과하는지 확인할 방법이 없었습니다.

이 실습은 Backstage 를 통째로 띄우지 않습니다 — 수백 MB 와 몇 분의 빌드가 걸립니다. 대신 카탈로그에 넣을 때 쓰는 바로 그 라이브러리를 직접 돌립니다.

스키마와 정책은 다른 것을 잡습니다

카탈로그는 두 층으로 거릅니다.

스키마   형태 — apiVersion·kind·필수 필드가 있는가정책     규칙 — 이름 형식, 63자 제한, 모르는 루트 필드 거부

entitySchemaValidator 만 쓰면 스키마만 봅니다. 그래서 이름에 공백이 있어도, spec 을 spce 로 잘못 써도 통과합니다. 진짜 카탈로그는 그 위에 정책을 얹습니다.

모르는 루트 필드를 막는 이유가 특히 값집니다. spce 오타가 통과하면 그 서비스는 spec 없이 — owner 도 lifecycle 도 없이 — 카탈로그에 들어갑니다. CNPA 의 구조적 스키마 잘라내기와 같은 정신입니다.

참조가 관계를 만듭니다

owner: team-a 는 사실 group:default/team-a 를 가리키는 참조입니다. 이 참조들이 모여 그래프가 되고, Backstage 화면의 "누가 소유하고 무엇에 의존하는가" 가 전부 이 그래프를 걸어간 결과입니다. 참조가 깨지면 관계가 끊깁니다 — 그래서 이름 형식이 엄격합니다.

설정은 키 단위로 깊게 병합됩니다

마지막 파일이 전부를 덮어쓰는 게 아닙니다. 스칼라는 뒤가 이기고, 한쪽에만 있는 키는 살아남고, 배열은 통째로 교체됩니다. 이 배열 규칙이 함정입니다.

실무에서 진짜 중요한 것

모르는 루트 필드를 거부하는 정책을 반드시 켭니다. spec 을 spce 로 쓴 오타가 통과하면 그 서비스는 owner 도 lifecycle 도 없이 카탈로그에 들어갑니다. 등록은 성공했는데 소유자가 비어 있는 항목이 쌓이는 것이 목록이 썩는 가장 흔한 경로입니다.

참조 형식이 엄격한 이유는 그것이 관계 그래프이기 때문입니다. owner: team-a 는 group:default/team-a 를 가리키는 참조이고, 화면의 "누가 소유하고 무엇에 의존하는가" 는 전부 이 그래프를 걸어간 결과입니다. 참조가 깨지면 관계가 통째로 끊깁니다.

설정 병합에서 배열은 통째로 교체됩니다. 스칼라는 뒤가 이기고 한쪽에만 있는 키는 살아남는데, 배열만 규칙이 다릅니다. 환경별 파일에 배열을 반쯤 적어 두면 앞 파일의 항목이 전부 사라집니다.

다음 실습에서 이것들을 진짜 라이브러리로 직접 거절당해 가며 확인합니다.