ADR009: 엔티티 참조(Entity References)
카탈로그 파일 형식의 사양은 잘 기술되어 있지만, 카탈로그에서 다른 엔티티에 대한 참조를 표현하는 방법에 대한 지침은 제공되지 않았습니다.
출처: 문서
본문
배경
카탈로그 파일 형식의 사양은 ADR002에 잘 기술되어 있지만, 카탈로그에서 다른 엔티티에 대한 참조를 어떻게 표현할 것으로 기대하는지에 대한 지침은 제공되지 않았습니다. 또한 Backstage 프론트엔드의 URL에서 엔티티를 참조하는 방법에 대한 혼란도 있었습니다.
Issue 1947에서의 논의에 따라 결정이 내려졌습니다.
YAML 파일에서의 엔티티 참조
사람이 이름으로 엔티티를 참조하기 위해 작성하는 텍스트 형식은 다음과 같은 형태이며, 대괄호는 선택 사항을 나타냅니다.
[<kind>:][<namespace>/]<name>
즉, 이 형식은 1개에서 3개의 부분으로, 특정 순서대로, 추가적인 인코딩 없이, 그 정확한 구분 문자들로 구성됩니다. kind와 namespace의 선택 여부는 맥락적이며, 기본 맥락적 대체 값을 가질 수도 있고 아닐 수도 있습니다.
그 형식이 부족하거나, 기계가 만든 상호 교환 형식이 그러한 관계를 더 표현력 있는 형식으로 표현하고자 할 때, 다음과 같은 형태의 중첩 구조를 사용할 수 있습니다.
kind: <kind>namespace: <namespace>name: <name>
이 중 항상 필요한 것은 name뿐입니다. kind와 namespace의 선택 여부는 맥락적이며, 기본 맥락적 대체 값을 가질 수도 있고 아닐 수도 있습니다. 이 구조의 다른 모든 가능한 키 값은 향후 사용을 위해 예약되어 있습니다.
항상 유효한 전체 엔티티 이름을 표현하고자 하는 시스템 또는 사용자는 문자열 형식이든 복합 형식이든 전체 삼중(triplet)을 제공해야 합니다.
형식에 대한 전체 설명은 문서에서 확인할 수 있습니다.
URL에서의 엔티티 참조
Backstage 프론트엔드에서 엔티티가 이름으로 참조되는 곳에서는, 참조를 포함하는 URL이 다음과 같은 형태를 취해야 합니다.
:namespace/:kind/:name
세 부분은 모든 상황에서 필수입니다. 엔티티가 metadata.namespace에 명시적으로 지정하지 않았다면, 카탈로그에서 namespace의 기본값은 문자열 "default"입니다.
즉, URL에 안전하지 않은 문자가 사용되어 가능한 위험, 혼란, 그리고 더 지저분한 URL로 이어질 수 있으므로, 엔티티 참조의 문자열 형식을 단일 URL 세그먼트로 사용하는 것을 권장하지 않습니다.