엔티티 참조
엔티티 참조 (Entity References)
엔티티는 흔히 다른 엔티티를 참조해야 하는 경우가 있습니다. 예를 들어 Component 엔티티는 Group 또는 User 엔티티를 언급해 자신의 소유자가 누구인지 선언하고 싶을 수 있고, User 엔티티는 자신이 어떤 Group 엔티티의 멤버인지 선언하고 싶을 수 있어요.
출처: 문서
본문
엔티티는 흔히 다른 엔티티를 참조해야 하는 경우가 있습니다. 예를 들어 Component 엔티티는 Group 또는 User 엔티티를 언급해 자신의 소유자가 누구인지 선언하고 싶을 수 있고, User 엔티티는 자신이 어떤 Group 엔티티의 멤버인지 선언하고 싶을 수 있어요. 이 문서는 yaml 엔티티 선언 파일에서 그러한 참조를 어떻게 작성하는지 설명합니다.
카탈로그의 각 엔티티는 종류(kind), 네임스페이스(namespace), 이름(name)의 세 쌍으로 고유하게 식별됩니다. 하지만 그것을 전부 손으로 입력하는 것은 번거롭고, 많은 상황에서 종류와 네임스페이스는 고정되어 있거나, 추론할 수 있거나, 합리적인 기본값이 있습니다. 그래서 작성자를 돕기 위해 카탈로그에는 몇 가지 요령이 있습니다.
각 참조는 두 가지 방식 중 하나로 표현할 수 있습니다. 간결한 문자열, 또는 복합 참조 구조입니다.
문자열 참조
이것이 가장 흔한 방식이며 거의 모든 상황에서 사용됩니다.
문자열은 [<kind>:][<namespace>/]<name> 형태입니다. 즉 특정 순서로 조합된 1~3개의 부분으로, 추가 인코딩 없이 구성됩니다.
- 선택적으로 종류(kind), 그 뒤에 콜론
- 선택적으로 네임스페이스, 그 뒤에 슬래시
- 이름
이름은 항상 필요합니다. 문맥에 따라 종류나 네임스페이스를 생략할 수 있습니다. 그렇게 하면 어떤 값이 사용될지는 맥락에 따라 달라지며, 관련 문서가 어디에 어떤 규칙이 적용되는지 명시해야 합니다.
엔티티 참조 문자열은 시스템 사이에서 엔티티의 식별자로 자주 전달됩니다. 그런 경우 참조는 항상 완전해야 합니다(세 부분을 모두 가져야 함). 보내는 쪽은 참조가 항상 en-US 로케일로 소문자화되도록 해야 하며, 가급적 이를 자동으로 처리하는 stringifyEntityRef 함수를 사용하는 것이 좋습니다. 받는 쪽은 이 규칙을 따르지 않는 보내는 쪽 때문에 생기는 문제를 피하기 위해 들어오는 참조를 대소문자 구분 없이 처리해야 합니다.
# Example:apiVersion: backstage.io/v1alpha1kind: Componentmetadata: name: petstore namespace: external-systems description: Petstorespec: type: service lifecycle: experimental owner: group:pet-managers providesApis: - petstore - internal/streetlights - hello-world
spec.owner 필드는 참조입니다. 이 경우 사용자가 문자열 group:pet-managers를 주었습니다. 즉 종류는 Group, 네임스페이스는 생략, 이름은 pet-managers입니다. 이 문맥에서 참조를 파싱한 코드가 네임스페이스를 default 값으로 폴백하도록 선택했으므로, 최종 결과는 카탈로그에서 종류가 Group이고 네임스페이스가 default(실제로는 자기 yaml 파일에서도 생략 가능한데 거기서도 기본값이기 때문이에요)이며 이름이 pet-managers인 다른 엔티티를 찾을 것으로 기대합니다.
providesApis의 항목도 참조입니다. 이 경우 문맥상 여기에서 지원되는 유일한 종류임을 알기 때문에 어떤 것도 종류를 명시할 필요가 없습니다. 두 번째 항목은 네임스페이스를 명시하지만 나머지는 명시하지 않는데, 이 문맥에서 기본값은 원래 엔티티와 같은 네임스페이스(여기서는 external-systems)를 가리키는 것입니다. 그래서 세 참조는 실질적으로 api:external-systems/petstore, api:internal/streetlights, api:external-systems/hello-world로 확장됩니다. 이 참조들과 일치하는 종류가 API인 세 엔티티가 카탈로그에 존재할 것으로 기대합니다.
단축(종류나 네임스페이스 생략)에 관한 위의 언급은 엔티티 입력 YAML 데이터에만 적용된다는 점에 주목하세요. 프로토콜, 저장 시스템, 또는 엔티티를 외부에서 참조할 때는 엔티티 참조가 항상 세 부분으로 구성됩니다.
복합 참조
이것은 참조의 더 장황한 버전으로, kind-namespace-name 세 쌍의 각 부분이 객체의 필드로 표현됩니다. Backstage 코드에서는 이 구조를 볼 수 있지만, 어떤 형태의 프로토콜이나 플러그인 간/외부 시스템 간에서는 보통 사용해서는 안 됩니다. 그런 경우에는 더 명확한 의미론을 갖고 문자열일 뿐이라 전송하기 쉬운 문자열 형태를 선호하세요.