ADR002: 기본 Software Catalog 파일 형식
Backstage에는 소프트웨어 카탈로그 기능이 포함되어 있어, 다양한 구성 요소를 추적할 수 있습니다.
출처: 문서
본문
배경
Backstage에는 소프트웨어 카탈로그 기능이 포함되어 있어 모든 소프트웨어 구성 요소와 그 외의 것들을 추적할 수 있습니다. 이 카탈로그는 다양한 소스의 데이터로 구동될 수 있으며, 패키지에 포함된 소스 중 하나는 커스텀 데이터베이스 기반 카탈로그입니다. 이 카탈로그는 선택한 버전 관리 시스템에 있는 작은 디스크립터 파일들의 내용에 따라 자동으로 최신 상태를 유지할 수 있습니다. 개발자가 이러한 파일을 만들고 코드와 나란히 유지 관리하면, 카탈로그 시스템이 그에 맞춰 반응합니다.
이 ADR은 이 디스크립터 파일들의 기본 형식을 설명합니다.
영감
Spotify 내부에서는 자체 개발한 소프트웨어 카탈로그 시스템이 활발히 사용되고 있으며, 이는 Backstage와 인프라의 다른 중요 부분의 핵심을 이룹니다. 그 카탈로그의 사용자 경험, 학습 내용, 일부 메타데이터 조각들이 오픈 소스 노력으로 이어지고 있습니다.
여기서 설명하는 파일 형식은 kubernetes 오브젝트 형식에서도 큰 영감을 받았습니다.
핵심 개념
여러 디스크립터 파일이 있으며, 이들의 위치(예: 버전 관리 시스템 내)는 모두 소프트웨어 카탈로그에 등록됩니다. 등록 방법은 이 문서의 범위를 벗어납니다. 등록은 Backstage 내부에서 수동으로, CI/CD 파이프라인의 push 이벤트로, 또는 버전 관리 시스템의 webhook 트리거 등으로 이루어질 수 있습니다.
각 파일은 Backstage System Model(BaaS)에 따라 하나 이상의 엔티티를 기술합니다. 이 모든 엔티티는 공통 구조와 명명 규칙을 가지며, 소프트웨어 카탈로그에 저장된 후 쿼리할 수 있습니다.
엔티티는 서로 구별되는 이름을 가지며, 그 이름으로 서로를 참조할 수 있습니다.
형식
디스크립터 파일은 YAML 형식을 사용합니다.
손으로 작성하거나 자동화된 도구로 만들 수 있습니다. 각 파일은 여러 YAML 문서(---로 구분)로 구성될 수 있으며, 각 문서는 하나의 엔티티를 기술합니다.
다음은 모의 데이터가 포함된 엔티티 정의 예시입니다.
---apiVersion: backstage.io/v1alpha1kind: Componentmetadata: name: frobs-awesome description: | Backend service that implements the Frobs API, as defined in [the Frobs RFC](https://example.com/spec/frob.html). labels: system: frobs lifecycle: production example.com/service-discovery-name: frobsawesome annotations: circleci.com/project-slug: github/example-org/frobs-awesomespec: type: service
루트 필드 apiVersion, kind, metadata, spec은 엔벨로프의 일부로, 모든 종류의 엔티티의 전체 구조를 정의합니다. 마찬가지로 name, namespace, labels, annotations 메타데이터 필드는 특별한 의미를 가지며 예약된 용도와 고유한 형태를 가집니다.
이 필드들에 대한 자세한 내용은 아래를 참조하세요.
엔벨로프
루트 엔벨로프 오브젝트는 다음과 같은 구조를 가집니다.
apiVersion과 kind
kind는 기술되는 엔티티의 상위 수준 유형으로, 일반적으로 Backstage 시스템 모델에서 가져옵니다. 카탈로그의 초기 버전은 Component kind에 초점을 맞출 것입니다.
apiVersion은 이 파일이 작성된 특정 엔티티에 대한 사양 형식의 버전입니다. 이 버전은 형식을 진화시킬 수 있게 해주며, apiVersion과 kind의 쌍은 파서가 문서의 나머지 내용을 해석하는 방법을 알 수 있을 만큼 충분해야 합니다.
Backstage 고유 엔티티는 같은 유형의 구조를 공유하는 다른 오브젝트들과 구분하기 위해 backstage.io/ 접두사가 붙은 apiVersion을 가집니다. 이는 예를 들어 Kubernetes 오브젝트 매니페스트와 함께 이 사양을 공동 호스팅할 때 관련이 있을 수 있습니다.
카탈로그의 초기 버전은 형식이 아직 바뀔 수 있음을 알리기 위해 알파/베타 버전(예: backstage.io/v1alpha1)을 사용합니다. 그 후에는 backstage.io/v1 이상을 사용할 것입니다.
metadata
엔티티에 대한 메타데이터를 담는 구조로, 즉 엔티티 사양 자체에 직접 속하지 않는 것들입니다. 이 구조에 대한 자세한 내용은 아래를 참조하세요.
spec
엔티티를 기술하는 실제 사양 데이터입니다.
spec의 정확한 구조는 apiVersion과 kind의 조합에 따라 달라지며, 일부 kind는 spec을 전혀 가지지 않을 수도 있습니다. 특정 kind의 사양 구조에 대해서는 이 문서의 아래쪽을 참조하세요.
메타데이터
metadata 루트 필드는 다음과 같은 중첩 구조를 가집니다.
name
엔티티의 이름입니다. 이 이름은 사람이 엔티티를 알아보기 위한 용도와, 기계 및 다른 구성 요소가 엔티티를 참조(예: URL 또는 다른 엔티티 사양 파일에서)하기 위한 용도 모두에 사용됩니다.
이름은 주어진 네임스페이스(지정된 경우) 내에서 kind별로, 어느 시점에나 고유해야 합니다. 이 고유성 제약은 대소문자를 구분하지 않습니다. 이름은 엔티티가 레지스트리에서 삭제된 후 나중에 재사용될 수 있습니다.
이름은 특정 형식을 따라야 합니다. 이 규칙을 따르지 않는 엔티티는 카탈로그 등록이 수락되지 않습니다. 규칙 집합은 조직의 필요에 맞게 구성할 수 있지만, 기본 동작은 다음과 같습니다.
-
길이가 1 이상, 최대 63인 문자열
-
[-_.]중 하나로 구분된[a-z0-9A-Z]시퀀스로 구성되어야 함
예: visits-tracking-service, CircleciBuildsDs_avro_gcs
namespace
엔티티가 속한 네임스페이스의 name입니다. 이 필드는 선택 사항이며, 지정된 경우 이름 고유성 제약을 묶는 것 외에는 현재 특별한 의미가 없습니다. 향후 사용을 위해 예약되어 있으며 더 넓은 의미론적 함의를 가질 수 있습니다.
네임스페이스는 카탈로그의 일부일 수도 있으며 v1 / Namespace 엔티티입니다. 즉, Backstage 고유가 아니라 Kubernetes와 동일합니다.
description
Backstage에서 표시될 엔티티에 대한 사람이 읽을 수 있는 설명입니다. 짧고 유익하게 유지하여, 엔티티의 목적을 한눈에 파악할 수 있어야 합니다. 더 자세한 설명과 문서는 다른 곳에 두어야 합니다.
labels
레이블은 엔티티에 붙는 선택적 key/value 쌍으로, kubernetes 오브젝트 레이블과 사용법이 동일합니다.
주요 목적은 다른 엔티티에 대한 참조와, 현재 엔티티를 어떤 식으로든 분류하는 정보를 위한 것입니다. 쿼리나 필터에서 값으로 자주 사용됩니다.
키와 값 모두 문자열이며, 다음 제한 사항을 따릅니다.
키는 선택적 접두사 뒤에 슬래시가 오고, 그 다음 필수인 이름 부분이 옵니다. 접두사는 유효한 소문자 도메인 이름이어야 하며, 총 253자 이하여야 합니다. 이름 부분은 [-_.] 중 하나로 구분된 [a-zA-Z0-9] 시퀀스여야 하며, 총 63자 이하여야 합니다.
backstage.io/ 접두사는 Backstage 핵심 구성 요소 전용으로 예약되어 있습니다. system과 같은 일부 키는 미리 정의된 의미론을 가지기도 합니다.
값은 위의 name과 동일한 제한 사항을 따르는 문자열입니다.
annotations
엔티티에 붙는 임의의 비식별 메타데이터를 담는 오브젝트로, kubernetes 오브젝트 어노테이션과 사용법이 동일합니다.
주요 목적은 외부 시스템을 참조하는 것이지만, 그것에만 국한되지는 않습니다. 예를 들어 엔티티가 수집된 git ref, 모니터링 및 로깅 시스템, pagerduty 일정 등에 대한 참조일 수 있습니다.
키와 값 모두 문자열이며, 다음 제한 사항을 따릅니다.
키는 선택적 접두사 뒤에 슬래시가 오고, 그 다음 필수인 이름 부분이 옵니다. 접두사는 유효한 소문자 도메인 이름이어야 하며, 총 253자 이하여야 합니다. 이름 부분은 [-_.] 중 하나로 구분된 [a-zA-Z0-9] 시퀀스여야 하며, 총 63자 이하여야 합니다.
backstage.io/ 접두사는 Backstage 핵심 구성 요소 전용으로 예약되어 있습니다.
값은 어떤 길이든 될 수 있지만 문자열로 제한됩니다.
Component
| | Field | Value | apiVersion | backstage.io/v1alpha1 | kind | Component
이 kind에 대한 spec 오브젝트는 다음과 같습니다.
| | Field | Type | Required | Description | type | String | Yes | 구성 요소의 유형, 예: service.