본문 바로가기
WIKI 기술 지식 베이스

카탈로그 엔티티의 Descriptor 형식

원문 보기 위키 갱신

이번 장에서는 카탈로그 엔티티(catalog entity)의 기본 데이터 형태와 의미를 설명할게요.

출처: 문서

본문

이번 장에서는 카탈로그 엔티티의 기본 데이터 형태와 의미를 설명해요.

이는 소프트웨어 카탈로그 API에 주고받는 객체에도 적용되고, 소프트웨어 카탈로그가 기본적으로 수집(ingest)할 수 있는 descriptor 파일에도 동일하게 적용돼요. API 요청·응답 과정에서는 JSON 표현을 쓰고, descriptor 파일은 사람이 유지보수하기 쉽도록 YAML 형식이에요. 다만 두 경우 모두 구조와 의미는 같아요.

카탈로그 엔티티 descriptor 파일의 이름은 원하는 대로 지을 수 있지만, catalog-info.yaml로 짓는 걸 권장해요.

목차

  • 엔티티의 전체적인 형태(Overall Shape Of An Entity)

  • 모든 종류에 공통: Envelope

  • 모든 종류에 공통: Metadata

  • 모든 종류에 공통: Relations

  • 모든 종류에 공통: Status

  • Kind: Component

  • Kind: Template

  • Kind: API

  • Kind: Group

  • Kind: User

  • Kind: Resource

  • Kind: System

  • Kind: Domain

  • Kind: Location

엔티티의 전체적인 형태(Overall Shape Of An Entity)

다음은 Component 엔티티의 descriptor 파일 예시예요.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
  labels:
    example.com/custom: custom_label_value
  annotations:
    example.com/service-discovery: artistweb
    circleci.com/project-slug: github/example-org/artist-website
  tags:
    - java
  links:
    - url: https://admin.example-org.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: website
  lifecycle: production
  owner: artist-relations-team
  system: public-websites

소프트웨어 카탈로그 API가 JSON으로 반환하는 동일한 엔티티는 다음과 같아요.

{
  "apiVersion": "backstage.io/v1alpha1",
  "kind": "Component",
  "metadata": {
    "annotations": {
      "backstage.io/managed-by-location": "file:/tmp/catalog-info.yaml",
      "example.com/service-discovery": "artistweb",
      "circleci.com/project-slug": "github/example-org/artist-website"
    },
    "description": "The place to be, for great artists",
    "etag": "ZjU2MWRkZWUtMmMxZS00YTZiLWFmMWMtOTE1NGNiZDdlYzNk",
    "labels": {
      "example.com/custom": "custom_label_value"
    },
    "links": [
      {
        "url": "https://admin.example-org.com",
        "title": "Admin Dashboard",
        "icon": "dashboard",
        "type": "admin-dashboard"
      }
    ],
    "tags": ["java"],
    "name": "artist-web",
    "uid": "2152f463-549d-4d8d-a94d-ce2b7676c6e2"
  },
  "spec": {
    "lifecycle": "production",
    "owner": "artist-relations-team",
    "type": "website",
    "system": "public-websites"
  }
}

루트 필드인 apiVersion, kind, metadata, spec은 envelope의 일부로, 모든 종류의 엔티티의 전체 구조를 정의해요. 마찬가지로 name, labels, annotations 같은 일부 metadata 필드는 특별한 의미를 지니며 예약된 용도와 고유한 형태를 가져요.

이 필드들에 대한 자세한 내용은 아래에서 다룰게요.

Descriptor 형식에서의 치환(Substitutions)

Descriptor 형식은 $text, $json, $yaml을 이용한 치환을 지원해요.

$json: https://example.com/entity.json 같은 플레이스홀더는 참조된 파일의 내용으로 치환돼요. 파일은 location과 마찬가지로, 절대 URL을 넘겨 어떤 구성된 integration에서든 참조할 수 있어요. 같은 location에서 ./referenced.yaml 같은 상대 파일을 참조하는 것도 가능해요. 상대 참조는 해당 플레이스홀더가 들어 있는 catalog-info.yaml의 폴더를 기준으로 해석돼요. 플레이스홀더에는 세 종류가 있어요.

  • $text: 참조된 파일의 내용을 일반 텍스트로 해석해서 문자열로 임베드해요.

  • $json: 참조된 파일의 내용을 JSON으로 해석해서 파싱된 구조를 임베드해요.

  • $yaml: 참조된 파일의 내용을 YAML로 해석해서 파싱된 구조를 임베드해요.

예를 들어, 이 기능을 이용해 웹 서버에서 API 엔티티의 정의를 불러와 spec.definition 필드에 문자열로 임베드할 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: petstore
  description: The Petstore API
spec:
  type: openapi
  lifecycle: production
  owner: [email protected]
  definition:
    $text: https://petstore.swagger.io/v2/swagger.json

github.com 같은 일반적인 integration 지점 밖의 대상에서 읽으려면 backend.reading.allow 목록에 항목을 추가해 명시적으로 허용해야 하는 점에 유의해요. 경로를 지정하면 대상을 더 제한할 수도 있어요. 예를 들면 이렇죠.

backend:
  baseUrl: ...
  reading:
    allow:
      - host: example.com
      - host: '*.examples.org'
      - host: example.net
        paths: ['/api/']

모든 종류에 공통: Envelope

루트 envelope 객체는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

kind는 설명 대상인 상위 수준의 엔티티 유형이에요. ADR005는 플러그인이 알고 이해할 수 있는 몇 가지 핵심 kind를 정의하지만, Backstage를 쓰는 조직이라면 카탈로그에 다른 kind의 엔티티를 자유롭게 추가할 수 있어요.

카탈로그가 초기 단계에서 집중하는, 아마도 가장 중심적인 엔티티 kind는 Component예요(아래 참조).

apiVersion은 해당 엔티티에 대한 명세(specification)가 기준으로 하는 형식의 버전이에요. 이 버전은 형식이 진화할 수 있게 해주고, 파서가 나머지 데이터를 해석하는 방법을 알기 위해서는 apiVersion과 kind의 조합만으로 충분해야 해요.

Backstage 전용 엔티티는 backstage.io/로 시작하는 apiVersion을 쓰는데, 같은 구조를 공유하는 다른 유형의 객체와 구분하기 위해서예요. 이 명세를 예를 들어 Kubernetes 객체 매니페스트와 함께 호스팅하거나, 조직이 자체적인 엔티티 kind를 카탈로그에 추가할 때 유용할 수 있어요.

카탈로그 초기 버전은 형식이 바뀔 수 있음을 알리기 위해 backstage.io/v1alpha1 같은 alpha/beta 버전을 사용할 거예요. 그 이후로는 backstage.io/v1부터 사용하게 돼요.

metadata [필수]

엔티티에 대한 메타데이터, 즉 엔티티 명세 자체의 일부는 아닌 정보를 담는 구조예요. 이 구조에 대한 자세한 내용은 아래에서 다룰게요.

spec [종류에 따라 다름]

엔티티를 설명하는 실제 명세 데이터예요.

spec의 정확한 구조는 apiVersion과 kind 조합에 따라 달라지고, 일부 kind는 spec이 아예 없을 수도 있어요. 특정 kind의 명세 구조는 이 문서 아래쪽에서 다룰게요.

모든 종류에 공통: Metadata

metadata 루트 필드에는 특정 의미를 지닌 예약 필드가 몇 개 있어요. 아래에서 설명할게요.

이 외에도 metadata 아래에 얼마든지 다른 필드를 추가할 수 있지만, 일반적인 플러그인과 도구가 그 의미를 이해하지 못할 수 있다는 점을 알아두세요. 자세한 내용은 모델 확장(Extending the model)을 참고해요.

name [필수]

엔티티의 이름이에요. 이 이름은 사람의 눈으로 엔티티를 알아보기 위한 용도이면서도, 기계와 다른 컴포넌트가 엔티티를 참조(예: URL이나 다른 엔티티 명세 파일에서)하는 용도로도 쓰여요.

이름은 주어진 namespace(지정된 경우) 안에서 kind별로, 어떤 시점에도 유일해야 해요. 이 유일성 제약은 대소문자를 구분하지 않아요. 엔티티가 레지스트리에서 삭제된 뒤에는 이름을 나중에 재사용할 수 있어요.

이름은 특정 형식을 따라야 해요. 이런 규칙을 지키지 않는 엔티티는 카탈로그에 등록이 거부돼요. 규칙 집합은 조직의 필요에 맞게 구성할 수 있지만, 기본 동작은 다음과 같아요.

  • 길이가 최소 1, 최대 63인 문자열

  • [a-z0-9A-Z]의 연속으로 구성되며 [-_.] 중 하나로 구분될 수 있음

예시: visits-tracking-service, CircleciBuildsDumpV2_avro_gcs

namespace [선택]

엔티티가 속한 namespace의 ID예요. 이 필드는 선택 사항이며, 지정된 경우 이름 유일성 제약의 범위를 제한하는 것 외에는 특별한 의미가 없어요.

이름이 겹칠 수 있는 서로 다른 환경에서 (같은 kind의) 엔티티를 수집할 때 유용해요. 예를 들어 HR 시스템의 사용자와 그룹을 기본 namespace로 가져오면서, GitHub enterprise 설치 환경의 사용자를 수집하려고 할 때 그 이름이 HR 시스템 사용자와 같을 수 있죠. 이때 GitHub enterprise 수집을 "ghe" namespace에 배치하면 충돌을 피할 수 있어요.

namespace를 지정하지 않으면 "default" 값을 가정해요.

namespace는 [a-zA-Z0-9]의 연속으로 구성되며 -로 구분될 수 있고, 전체 길이가 최대 63자예요. namespace 이름은 대소문자를 구분하지 않으며 대부분의 곳에서 소문자로 렌더링돼요.

예시: tracking-services, payment

namespace를 쓰면 보통 엔티티를 참조할 때 namespace를 명시적으로 지정해야 한다는 점에 유의해요. 일부 환경, 특히 엔티티 catalog-info 정의 YAML 파일에서는 종종 이름으로 다른 엔티티를 참조하게 되는데, 다른 namespace에 있으면 <namespace>/<name> 구문을 써야 해요. 기본 namespace에 있으면 그 부분을 생략하는 축약형을 쓸 수 있어요. 그래서 보조 namespace가 필요해지기 전까지는 기본 namespace를 쓰는 것이 실용적이에요. 자세한 내용은 references 문서를 참고해요.

uid [출력]

각 엔티티는 데이터베이스에 처음 들어갈 때 자동으로 생성된 전역 고유 ID를 받아요. 이 필드는 입력 데이터로 지정하는 게 아니라, 출력 엔티티를 만들 때 데이터베이스 엔진이 직접 생성하는 것이에요.

uid 값은 안정적인 것으로 보아선 안 되고, 엔티티에 대한 외부 참조로 사용해서도 안 돼요. 사람이 보기에는 바뀌지 않을 것 같아도 uid는 시간이 지나면서 바뀔 수 있어요. 많은 예 중 하나로, 정확히 같은 파일을 등록 취소하고 다시 등록하면 다른 모든 것이 같더라도 uid 값은 달라져요. 따라서 이 필드를 외부에서 읽거나 사용할 이유는 거의, 사실상 없어요.

엔티티를 어떤 식별자로 참조하고 싶다면 항상 문자열 형태의 엔티티 참조(entity reference)를 사용해야 해요.

title [선택]

엔티티의 표시 이름으로, 사용 가능한 경우 위의 name 속성 대신 사용자 인터페이스에 표시돼요.

name이 다루기 불편하거나 지나치게 기술적으로 느껴질 때 유용해요. title은 보통 그만큼 엄격한 형식 요구사항이 없어서 특수 문자를 포함할 수 있고 더 설명적으로 쓸 수 있어요. 다만 아주 짧게 유지하고, 어떤 엔티티의 이름과 혼동될 수 있거나 두 엔티티가 같은 title을 공유하는 상황은 피하도록 해요.

이것은 표시 목적일 뿐이고 일부 코드에서는 무시될 수 있다는 점을 알아두세요. 예를 들어 엔티티 참조는 여전히 항상 name 속성을 사용하지, title을 사용하지 않아요.

description [선택]

Backstage에 표시할, 사람이 읽을 수 있는 엔티티 설명이에요. 짧고 유익하게 유지해, 한눈에 엔티티의 목적을 파악할 수 있게 하는 것이 좋아요. 더 자세한 설명과 문서는 다른 곳에 두어야 해요.

labels [선택]

Labels는 엔티티에 붙는 선택적인 키/값 쌍으로, 사용법은 Kubernetes 객체 labels와 동일해요.

주 용도는 다른 엔티티에 대한 참조와, 어떤 방식으로든 현재 엔티티를 분류하는 정보를 담는 것이에요. 쿼리나 필터의 값으로 자주 쓰여요.

키와 값 모두 문자열이며 다음 제한을 따라요.

키는 선택적 접두사 뒤에 슬래시, 그리고 필수인 이름 부분으로 구성돼요. 접두사가 있으면 유효한 소문자 도메인 이름이어야 하고 전체 길이가 최대 253자예요. 이름 부분은 [-_.] 중 하나로 구분되는 [a-zA-Z0-9]의 연속이어야 하며 총 길이가 최대 63자예요.

backstage.io/ 접두사는 Backstage 핵심 컴포넌트용으로 예약되어 있어요.

값은 위의 name과 같은 제한을 따르는 문자열이에요.

annotations [선택]

엔티티에 붙는, 식별성이 없는 임의의 메타데이터 객체로, 사용법은 Kubernetes 객체 annotations와 동일해요.

주 용도는 (그것만은 아니지만) 외부 시스템을 참조하는 것이에요. 예를 들어 엔티티를 수집한 git ref에 대한 참조, 모니터링·로깅 시스템, PagerDuty 스케줄 등이 될 수 있어요. 사용자가 descriptor YAML 파일에 추가할 수도 있지만, 자동화된 시스템이 카탈로그 수집 중이거나 나중에 annotations를 추가할 수도 있어요.

키와 값 모두 문자열이며 다음 제한을 따라요.

키는 선택적 접두사 뒤에 슬래시, 그리고 필수인 이름 부분으로 구성돼요. 접두사가 있으면 유효한 소문자 도메인 이름이어야 하고 전체 길이가 최대 253자예요. 이름 부분은 [-_.] 중 하나로 구분되는 [a-zA-Z0-9]의 연속이어야 하며 총 길이가 최대 63자예요.

backstage.io/ 접두사는 Backstage 핵심 컴포넌트용으로 예약되어 있어요.

값은 길이 제한이 없지만 문자열로 제한돼요.

잘 알려진 annotations 목록이 있지만, 누구든 필요에 따라 더 추가할 자유가 있어요.

tags [선택]

단일 값 문자열의 목록으로, 예를 들어 카탈로그 엔티티를 여러 방식으로 분류하는 데 쓰여요. metadata의 labels와는 달리, labels는 키/값 쌍이라는 점에서 차이가 있어요.

값은 사용자가 정의하는데, 예를 들어 컴포넌트에 사용된 프로그래밍 언어인 java나 go 같은 게 될 수 있어요.

이 필드는 선택 사항이며 현재 특별한 의미는 없어요.

각 tag는 -로 구분되는 [a-z0-9:+#]의 연속이어야 하며 총 길이가 최대 63자예요.

엔티티와 관련된 외부 하이퍼링크 목록이에요. 링크는 Backstage 자체 밖에 있을 수 있는 추가적인 상황 정보를 제공할 수 있어요. 예를 들어 관리자 대시보드나 외부 CMS 페이지가 그렇죠.

사용자는 descriptor YAML 파일에 링크를 추가해 외부 콘텐츠와 리소스에 대한 추가 참조 정보를 제공할 수 있어요. 링크는 Backstage 내부에서 추가 기능을 구동하기 위한 것이 아니며, 그런 역할은 annotations와 labels에 맡기는 것이 좋아요. 동등한 잘 알려진 annotation이 비슷한 사용 사례를 다루지 않을 때에만 링크를 쓰는 것을 권장해요.

링크의 필드는 다음과 같아요.

| Field | Type | Description | | url | String | [필수] 표준 uri 형식의 url (예: https://example.com/some/page) | | title | String | [선택] 링크의 사용자 친화적인 표시 이름 | | icon | String | [선택] UI에 표시할 시각적 아이콘을 나타내는 키 | | type | String | [선택] 링크를 특정 그룹으로 분류하기 위한 선택 값 |

note

icon 필드 값은 아이콘 라이브러리(예: material-ui 아이콘)가 제공할 수 있는 특정 아이콘에 매핑되는 의미론적 키로 의도된 것이에요. 이 키는 [-_.] 중 하나로 구분되는 [a-z0-9A-Z]의 연속이어야 해요. Backstage는 app-defaults에 정의된 것 같은 몇 가지 기본 아이콘을 지원할 수 있지만, 궁극적으로는 Backstage 통합자가 적절한 아이콘 컴포넌트 매핑을 제공해야 해요. 매핑을 해결하지 못하면 일반적인 대체(fallback) 아이콘이 제공돼요.

type 필드의 의미는 정의되어 있지 않아요. 도입하는 조직이 자신만의 type 집합을 정의하고 원하는 대로 활용할 자유가 있어요. 예를 들어 특정 링크가 엔티티에 존재하는지 검증하거나, 특정 링크 유형에 맞는 맞춤형 UI 컴포넌트를 만드는 데 쓰일 수 있어요.

모든 종류에 공통: Relations

relations 루트 필드는 현재 엔티티와 다른 엔티티 사이의 관계에 대한 읽기 전용 목록으로, 잘 알려진 relations(well-known relations) 섹션에 설명되어 있어요. 관계는 보통 양방향이라, 관계의 각 방향을 설명하는 관계 유형 쌍이 존재해요.

API에서 읽어낸 단일 엔티티의 일부로 나타나는 relation은 다음과 같을 수 있어요.

{
  // ...
  "relations": [
    {
      "type": "ownedBy",
      "targetRef": "group:default/dev.infra"
    }
  ],
  "spec": {
    "owner": "dev.infra",
    // ...
  }
}

relation의 필드는 다음과 같아요.

| Field | Type | Description | | targetRef | String | 관계의 반대쪽 끝을 가리키는 전체 엔티티 참조 | | type | String | 소스 엔티티에서 대상 엔티티로 향하는 관계의 유형 | | metadata | Object | 향후 사용을 위해 예약됨 |

엔티티 descriptor YAML 파일에는 이 필드가 들어가지 않아야 해요. 대신 카탈로그 프로세서가 엔티티 descriptor 데이터와 주변을 분석해 관계를 추론하고, 이를 카탈로그에서 읽어낸 엔티티에 붙여요.

관계가 생성되는 곳에서는 그 관계가 해당 데이터 조각의 권위 있는 출처로 간주돼야 해요. 위 예시에서 플러그인은 엔티티의 소유자를 추론할 때 spec.owner보다 관계를 소비하는 것이 더 나아요. 소유자가 YAML에서 전혀 가져오지 않을 수도 있기 때문이에요. 예를 들어 근처의 CODEOWNERS 파일에서 가져올 수도 있죠. 또한 spec.owner는 축약형이며 그와 연관된 의미가 있을 수 있어요(지정하지 않으면 기본 kind가 Group인 것처럼).

잘 알려진/일반적인 relations와 그 의미 목록은 잘 알려진 relations(well-known relations) 섹션을 참고해요.

모든 종류에 공통: Status

status 루트 객체는 엔티티의 현재 상태나 건강 상태에 관한 읽기 전용 상태 집합으로, 잘 알려진 statuses(well-known statuses) 섹션에 설명되어 있어요.

현재 정의된 필드는 items 배열뿐이에요. 각 항목은 특정 시스템의 관점에서 본 엔티티 상태의 어떤 측면을 설명하는 특정 데이터 구조를 담아요. 여러 시스템이 각자 자신의 type 키 아래에서 이 배열에 기여할 수 있어요.

이 필드의 현재 주 사용 사례는 카탈로그 자체의 수집 프로세스가 오류와 경고에 대한 정보를 사용자에게 전달하는 것이에요.

API에서 읽어낸 단일 엔티티의 일부로 나타나는 status 필드는 다음과 같을 수 있어요.

{
  // ...
  "status": {
    "items": [
      {
        "type": "backstage.io/catalog-processing",
        "level": "error",
        "message": "NotFoundError: File not found",
        "error": {
          "name": "NotFoundError",
          "message": "File not found",
          "stack": "..."
        }
      }
    ]
  },
  "spec": {
    // ...
  }
}

status 항목의 필드는 다음과 같아요.

| Field | Type | Description | | type | String | 소스별 고유 키로 사용되는 status의 유형. 각 유형은 배열에 두 번 이상 나타날 수 있음 | | level | String | status 항목의 수준/심각도: 'info', 'warning', 'error' | | message | String | 상태를 설명하는, 사람이 읽기 위한 짧은 메시지 | | error | Object | status와 관련된, 직렬화된 선택적 오류 객체 |

type은 임의의 문자열이지만, 조직 내부에서만 쓰이는 것이 아닌 유형은 충돌을 피하기 위해 네임스페이스를 붙일 것을 권장해요. Backstage 핵심 프로세스가 내보내는 유형은 위 예시처럼 backstage.io/로 시작해요.

엔티티 descriptor YAML 파일에는 status 루트 키가 들어가지 않아야 해요. 대신 카탈로그 프로세서가 엔티티 descriptor 데이터와 주변을 분석해 status 항목을 추론하고, 이를 카탈로그에서 읽어낸 엔티티에 붙여요.

잘 알려진/일반적인 status 유형 목록은 잘 알려진 statuses(well-known statuses) 섹션을 참고해요.

Kind: Component

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | Component |

Component는 소프트웨어 컴포넌트를 설명해요. 보통 컴포넌트를 구성하는 소스 코드와 밀접하게 연결되어 있고, 개발자가 "소프트웨어 단위"로 보는 것, 일반적으로 뚜렷한 배포 가능하거나 연결 가능한 아티팩트를 가리켜요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
spec:
  type: website
  lifecycle: production
  owner: artist-relations-team
  system: artist-engagement-portal
  dependsOn:
    - resource:default/artists-db
  dependencyOf:
    - component:default/artist-web-lookup
  providesApis:
    - artist-api

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 Component와 같아요.

spec.type [필수]

문자열 형태의 컴포넌트 유형, 예: website. 이 필드는 필수예요.

소프트웨어 카탈로그는 어떤 type 값이든 받아들이지만, 조직은 이에 대한 적절한 분류 체계(taxonomy)를 세우는 데 각별히 신경 써야 해요. Backstage 자신을 포함한 도구가 이 필드를 읽고 값에 따라 다르게 동작할 수 있어요. 예를 들어 website 유형의 컴포넌트는 Backstage 인터페이스에서 웹사이트에 특화된 도구를 보여줄 수 있어요.

이 필드의 현재 잘 알려진/일반적인 값은 다음과 같아요.

  • service - 백엔드 서비스, 보통 API를 노출함

  • website - 웹사이트

  • library - npm 모듈이나 Java 라이브러리 같은 소프트웨어 라이브러리

spec.lifecycle [필수]

컴포넌트의 수명 주기 상태, 예: production. 이 필드는 필수예요.

소프트웨어 카탈로그는 어떤 lifecycle 값이든 받아들이지만, 조직은 이에 대한 적절한 분류 체계를 세우는 데 각별히 신경 써야 해요.

이 필드의 현재 잘 알려진/일반적인 값은 다음과 같아요.

  • experimental - 실험이거나 초기의, 비프로덕션 컴포넌트로, 사용자가 다른 더 확립된 컴포넌트보다 이를 선호하지 않을 수 있거나 신뢰성 보장이 낮거나 없음을 나타냄

  • production - 확립되고, 소유되고, 유지보수되는 컴포넌트

  • deprecated - 수명 주기가 끝나가고 있으며 나중에 사라질 수 있는 컴포넌트

spec.owner [필수]

컴포넌트 소유자에 대한 엔티티 참조, 예: artist-relations-team. 이 필드는 필수예요.

Backstage에서 컴포넌트의 소유자는 컴포넌트에 대한 궁극적인 책임을 지는 단일 엔티티(보통 팀)로, 그것을 개발하고 유지보수할 권한과 역량을 가져요. 무언가 잘못되거나 기능 요청이 있을 때 연락할 대상이 바로 그 사람들이에요. 이 필드의 주 용도는 Backstage에서 표시용으로, 카탈로그 항목을 보는 사람들이 이 컴포넌트가 누구 것인지 알 수 있게 하는 것이에요. 런타임 시스템에서 권한을 할당하는 등의 자동화 프로세스에 사용해서는 안 돼요. 컴포넌트를 개발하거나 만지는 다른 사람들이 있을 수 있지만, 궁극적인 소유자는 항상 한 명이에요.

| kind | Default namespace | Generated relation type | | Group (default), User | 이 엔티티와 같음, 보통 default | ownedBy, 그리고 역방향 ownerOf |

spec.system [선택]

컴포넌트가 속한 시스템에 대한 엔티티 참조, 예: artist-engagement-portal. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | System (default) | 이 엔티티와 같음, 보통 default | partOf, 그리고 역방향 hasPart |

spec.subcomponentOf [선택]

컴포넌트가 그 일부가 되는 다른 컴포넌트에 대한 엔티티 참조, 예: spotify-ios-app. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | Component (default) | 이 엔티티와 같음, 보통 default | partOf, 그리고 역방향 hasPart |

spec.providesApis [선택]

컴포넌트가 제공하는 API에 대한 엔티티 참조 배열, 예: artist-api. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | API (default) | 이 엔티티와 같음, 보통 default | providesApi, 그리고 역방향 apiProvidedBy |

spec.consumesApis [선택]

컴포넌트가 소비하는 API에 대한 엔티티 참조 배열, 예: artist-api. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | API (default) | 이 엔티티와 같음, 보통 default | consumesApi, 그리고 역방향 apiConsumedBy |

spec.dependsOn [선택]

컴포넌트가 의존하는 컴포넌트와 리소스에 대한 엔티티 참조 배열, 예: artists-db. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | Component | 이 엔티티와 같음, 보통 default | dependsOn, 그리고 역방향 dependencyOf | | Resource | 이 엔티티와 같음, 보통 default | dependsOn, 그리고 역방향 dependencyOf |

spec.dependencyOf [선택]

컴포넌트가 그 의존 대상이 되는 컴포넌트와 리소스에 대한 엔티티 참조 배열, 예: artist-web-lookup. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | Component | 이 엔티티와 같음, 보통 default | dependencyOf, 그리고 역방향 dependsOn | | Resource | 이 엔티티와 같음, 보통 default | dependencyOf, 그리고 역방향 dependsOn |

Kind: Template

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1beta2 | | kind | Template |

템플릿 정의는 스캐폴딩(scaffolding) 마법사의 프런트엔드 부분에서 렌더링되는 매개변수와, 그 컴포넌트를 스캐폴딩할 때 실행되는 단계를 모두 설명해요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1beta2
kind: Template
# some metadata about the template itself
metadata:
  name: v1beta2-demo
  title: Test Action template
  description: scaffolder v1beta2 template demo
  annotations:
    backstage.io/time-saved: PT4H
spec:
  owner: backstage/techdocs-core
  type: service
  # these are the steps which are rendered in the frontend with the form input
  parameters:
    - title: Fill in some steps
      required:
        - name
      properties:
        name:
          title: Name
          type: string
          description: Unique name of the component
          ui:autofocus: true
          ui:options:
            rows: 5
    - title: Choose a location
      required:
        - repoUrl
      properties:
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com
  # here's the steps that are executed in series in the scaffolder backend
  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      input:
        url: ./template
        values:
          name: '{{ parameters.name }}'
    - id: fetch-docs
      name: Fetch Docs
      action: fetch:plain
      input:
        targetPath: ./community
        url: https://github.com/backstage/community/tree/main/backstage-community-sessions
    - id: publish
      name: Publish
      action: publish:github
      input:
        description: 'This is {{ parameters.name }}'
        repoUrl: '{{ parameters.repoUrl }}'
    - id: register
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: {{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: '/catalog-info.yaml'

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1beta2와 Template과 같아요.

metadata.tags [선택]

템플릿과 연관시킬 수 있는 문자열 목록, 예: ['recommended', 'react'].

이 목록은 프런트엔드에서 사용자에게 표시하는 데도 쓰여, 이 tags로 템플릿을 검색하고 그룹화할 수 있어요.

metadata.annotations.[backstage.io/time-saved] [선택]

누군가 이 템플릿을 사용할 때 대략 절약되는 시간을 나타내는 ISO 8601 기간(예: PT8H는 "8시간 절약", PT15M은 "15분 절약"을 뜻해요).

backstage.io/source-template annotation이나 분석(analytics) 데이터와 함께 사용해 Scaffolder 플러그인 사용을 통해 절약된 시간을 계산할 수 있어요.

spec.type [필수]

템플릿이 만드는 컴포넌트의 유형, 예: website. 템플릿을 필터링하는 데 사용되며, 이상적으로는 템플릿이 만드는 Component의 spec.type과 일치해야 해요.

spec.parameters [필수]

parameters 키에 대한 자세한 내용은 여기에서 확인할 수 있어요.

spec.steps [필수]

steps 키에 대한 자세한 내용은 여기에서 확인할 수 있어요.

spec.owner [선택]

템플릿 소유자에 대한 엔티티 참조, 예: artist-relations-team. 이 필드는 필수예요.

Backstage에서 Template의 소유자는 Template에 대한 궁극적인 책임을 지는 단일 엔티티(보통 팀)로, 그것을 개발하고 유지보수할 권한과 역량을 가져요. 무언가 잘못되거나 기능 요청이 있을 때 연락할 대상이 바로 그 사람들이에요. 이 필드의 주 용도는 Backstage에서 표시용으로, 카탈로그 항목을 보는 사람들이 이 Template이 누구 것인지 알 수 있게 하는 것이에요. 런타임 시스템에서 권한을 할당하는 등의 자동화 프로세스에 사용해서는 안 돼요. Template을 개발하거나 만지는 다른 사람들이 있을 수 있지만, 궁극적인 소유자는 항상 한 명이에요.

| kind | Default namespace | Generated relation type | | Group (default), User | 이 엔티티와 같음, 보통 default | ownedBy, 그리고 역방향 ownerOf |

Kind: API

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | API |

API는 컴포넌트가 노출할 수 있는 인터페이스를 설명해요. API는 OpenAPI, AsyncAPI, GraphQL, gRPC 등의 다양한 형식으로 정의할 수 있어요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: artist-api
  description: Retrieve artist details
spec:
  type: openapi
  lifecycle: production
  owner: artist-relations-team
  system: artist-engagement-portal
  definition: |
    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Artist API
      license:
        name: MIT
    servers:
      - url: http://artist.spotify.net/v1
    paths:
      /artists:
        get:
          summary: List all artists
    ...

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 API와 같아요.

spec.type [필수]

문자열 형태의 API 정의 유형, 예: openapi. 이 필드는 필수예요.

소프트웨어 카탈로그는 어떤 type 값이든 받아들이지만, 조직은 이에 대한 적절한 분류 체계를 세우는 데 각별히 신경 써야 해요. Backstage 자신을 포함한 도구가 이 필드를 읽고 값에 따라 다르게 동작할 수 있어요. 예를 들어 OpenAPI 유형의 API는 Backstage 인터페이스에서 OpenAPI 뷰어 도구로 표시될 수 있어요.

이 필드의 현재 잘 알려진/일반적인 값은 다음과 같아요.

  • openapi - OpenAPI 버전 2 또는 버전 3 스펙에 기반한 YAML 또는 JSON 형식의 API 정의

  • asyncapi - AsyncAPI 버전 2 또는 버전 3 스펙에 기반한 API 정의

  • graphql - GraphQL 기반 API를 소비하기 위한 GraphQL 스키마에 기반한 API 정의

  • grpc - gRPC와 함께 사용하기 위한 Protocol Buffers에 기반한 API 정의

spec.lifecycle [필수]

API의 수명 주기 상태, 예: production. 이 필드는 필수예요.

소프트웨어 카탈로그는 어떤 lifecycle 값이든 받아들이지만, 조직은 이에 대한 적절한 분류 체계를 세우는 데 각별히 신경 써야 해요.

이 필드의 현재 잘 알려진/일반적인 값은 다음과 같아요.

  • experimental - 실험이거나 초기의, 비프로덕션 API로, 사용자가 다른 더 확립된 API보다 이를 선호하지 않을 수 있거나 신뢰성 보장이 낮거나 없음을 나타냄

  • production - 확립되고, 소유되고, 유지보수되는 API

  • deprecated - 수명 주기가 끝나가고 있으며 나중에 사라질 수 있는 API

spec.owner [필수]

컴포넌트 소유자에 대한 엔티티 참조, 예: artist-relations-team. 이 필드는 필수예요.

Backstage에서 API의 소유자는 API에 대한 궁극적인 책임을 지는 단일 엔티티(보통 팀)로, 그것을 개발하고 유지보수할 권한과 역량을 가져요. 무언가 잘못되거나 기능 요청이 있을 때 연락할 대상이 바로 그 사람들이에요. 이 필드의 주 용도는 Backstage에서 표시용으로, 카탈로그 항목을 보는 사람들이 이 API가 누구 것인지 알 수 있게 하는 것이에요. 런타임 시스템에서 권한을 할당하는 등의 자동화 프로세스에 사용해서는 안 돼요. API를 개발하거나 만지는 다른 사람들이 있을 수 있지만, 궁극적인 소유자는 항상 한 명이에요.

| kind | Default namespace | Generated relation type | | Group (default), User | 이 엔티티와 같음, 보통 default | ownedBy, 그리고 역방향 ownerOf |

spec.system [선택]

API가 속한 시스템에 대한 엔티티 참조, 예: artist-engagement-portal. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | System (default) | 이 엔티티와 같음, 보통 default | partOf, 그리고 역방향 hasPart |

spec.definition [필수]

spec.type이 정의한 형식에 기반한 API의 정의. 이 필드는 필수예요.

Note: spec.definition 안에 API의 base URL을 명시하도록 하세요. 제공하지 않으면 일부 위젯(예: OpenAPI)이 Backstage 인스턴스의 base URL로 폴백해요. 각 형식별 API base URL 지정 예시는 다음과 같아요.

  • OpenAPI 3.x - server 필드 사용

  • OpenAPI 2.0 (Swagger) — host, basePath, schemes 사용

  • AsyncAPI - server 필드 사용

Kind: Group

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | Group |

Group은 조직 엔티티를 설명해요. 예를 들어 팀, 사업부, 또는 관심 그룹의 느슨한 사람 모임이 될 수 있어요. 이러한 그룹의 구성원은 카탈로그에서 kind User로 모델링돼요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: infrastructure
  description: The infra business unit
spec:
  type: business-unit
  profile:
    displayName: Infrastructure
    email: [email protected]
    picture: https://example.com/groups/bu-infrastructure.jpeg
  parent: ops
  children: [backstage, other]
  members: [jdoe]

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 Group과 같아요.

spec.type [필수]

문자열 형태의 그룹 유형, 예: team. 현재 이 필드에 강제되는 값 집합은 없어서, 조직 계층 구조와 맞는 명명 체계를 고르는 것은 도입 조직에 달려 있어요.

이 필드의 몇 가지 일반적인 값은 다음과 같을 수 있어요.

  • team

  • business-unit

  • product-area

  • root - 원한다면 계층 구조의 공통적인 가상 루트로 사용

spec.profile [선택]

주로 표시 목적의 그룹에 대한 선택적 프로필 정보예요. 이 구조의 모든 필드도 선택 사항이에요. email은 그룹이 연락용으로 쓰길 원하는 어떤 형태의 그룹 이메일이에요. picture는 그룹을 대표하는 이미지를 가리키는 URL로, 브라우저가 가져와 그룹 페이지 등에서 렌더링할 수 있을 것으로 기대돼요.

profile의 필드는 다음과 같아요.

| Field | Type | Description | | displayName (optional) | String | 그룹의 사람이 읽을 수 있는 이름 | | email (optional) | String | 그룹이 연락용으로 쓰길 원하는 이메일 | | picture (optional) | String | 그룹을 대표하는 이미지를 가리키는 URL |

spec.parent [선택]

있을 경우 계층 구조에서의 직속 상위 그룹이에요. 모든 그룹이 parent를 가질 필요는 없어요. 카탈로그는 다중 루트 계층 구조를 지원해요. 다만 그룹은 둘 이상의 parent를 가질 수는 없어요.

이 필드는 엔티티 참조예요.

| kind | Default namespace | Generated relation type | | Group (default) | 이 엔티티와 같음, 보통 default | childOf, 그리고 역방향 parentOf |

spec.children [필수]

계층 구조에서 이 그룹의 직속 하위 그룹(그 parent 필드가 이 그룹을 가리키는 그룹)이에요. 목록은 반드시 있어야 하지만 하위 그룹이 없으면 비어 있어도 돼요. 항목 순서는 특정 순서를 보장하지 않아요.

이 배열의 항목은 엔티티 참조예요.

| kind | Default namespace | Generated relation type | | Group (default) | 이 엔티티와 같음, 보통 default | parentOf, 그리고 역방향 childOf |

spec.members [선택]

이 그룹의 직접 구성원인 사용자들이에요. 항목 순서는 특정 순서를 보장하지 않아요.

이 배열의 항목은 엔티티 참조예요.

| kind | Default namespace | Generated relation type | | User (default) | 이 엔티티와 같음, 보통 default | hasMember, 그리고 역방향 memberOf |

Kind: User

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | User |

User는 직원, 계약자 같은 사람을 설명해요. 사용자는 카탈로그에서 Group 엔티티에 속해요.

이 카탈로그 사용자 항목은 Backstage 생태계 안에서 인증이 동작하는 방식과 연결되어 있어요. 이러한 개념에 대한 논의는 문서의 auth 섹션을 참고해요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: jdoe
spec:
  profile:
    displayName: Jenny Doe
    email: [email protected]
    picture: https://example.com/staff/jenny-with-party-hat.jpeg
  memberOf: [team-b, employees]

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 User와 같아요.

spec.profile [선택]

주로 표시 목적의 사용자에 대한 선택적 프로필 정보예요. 이 구조의 모든 필드도 선택 사항이에요. email은 사용자가 연락용으로 쓰길 원하는 어떤 형태의 기본 이메일이에요. picture는 사용자를 대표하는 이미지를 가리키는 URL로, 브라우저가 가져와 프로필 페이지 등에서 렌더링할 수 있을 것으로 기대돼요.

profile의 필드는 다음과 같아요.

| Field | Type | Description | | displayName (optional) | String | 사용자의 사람이 읽을 수 있는 이름 | | email (optional) | String | 사용자가 연락용으로 쓰길 원하는 이메일 | | picture (optional) | String | 사용자를 대표하는 이미지를 가리키는 URL |

spec.memberOf [필수]

사용자가 직접 구성원인 그룹의 목록(즉, 여기에는 전이적 멤버십은 나열되지 않아요)이에요. 목록은 반드시 있어야 하지만 어떤 그룹의 구성원이 아니면 비어 있어도 돼요. 항목 순서는 특정 순서를 보장하지 않아요.

이 배열의 항목은 엔티티 참조예요.

| kind | Default namespace | Generated relation type | | Group (default) | 이 엔티티와 같음, 보통 default | memberOf, 그리고 역방향 hasMember |

Kind: Resource

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | Resource |

Resource는 시스템이 동작하는 데 필요한 인프라스트럭처를 설명해요. BigTable 데이터베이스, Pub/Sub 토픽, S3 버킷, CDN 같은 것들이죠. 이것들을 컴포넌트·시스템과 함께 모델링하면 리소스 사용량을 시각화하고 그 주변에 도구를 만들 수 있어요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: artists-db
  description: Stores artist details
spec:
  type: database
  owner: artist-relations-team
  system: artist-engagement-portal

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 Resource와 같아요.

spec.owner [필수]

리소스 소유자에 대한 엔티티 참조, 예: artist-relations-team. 이 필드는 필수예요.

Backstage에서 리소스의 소유자는 리소스에 대한 궁극적인 책임을 지는 단일 엔티티(보통 팀)로, 그것을 개발하고 유지보수할 권한과 역량을 가져요. 무언가 잘못되거나 기능 요청이 있을 때 연락할 대상이 바로 그 사람들이에요. 이 필드의 주 용도는 Backstage에서 표시용으로, 카탈로그 항목을 보는 사람들이 이 리소스가 누구 것인지 알 수 있게 하는 것이에요. 런타임 시스템에서 권한을 할당하는 등의 자동화 프로세스에 사용해서는 안 돼요. 리소스를 관리하거나 만지는 다른 사람들이 있을 수 있지만, 궁극적인 소유자는 항상 한 명이에요.

| kind | Default namespace | Generated relation type | | Group (default), User | 이 엔티티와 같음, 보통 default | ownedBy, 그리고 역방향 ownerOf |

spec.type [필수]

문자열 형태의 리소스 유형, 예: database. 이 필드는 필수예요. 현재 이 필드에 강제되는 값 집합은 없어서, 자신들의 기술 스택에서 쓰는 리소스와 맞는 명명 체계를 고르는 것은 도입 조직에 달려 있어요.

이 필드의 몇 가지 일반적인 값은 다음과 같을 수 있어요.

  • database

  • s3-bucket

  • kubernetes-cluster

spec.system [선택]

리소스가 속한 시스템에 대한 엔티티 참조, 예: artist-engagement-portal. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | System (default) | 이 엔티티와 같음, 보통 default | partOf, 그리고 역방향 hasPart |

spec.dependsOn [선택]

리소스가 의존하는 컴포넌트와 리소스에 대한 엔티티 참조 배열, 예: artist-lookup. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | Component | 이 엔티티와 같음, 보통 default | dependsOn, 그리고 역방향 dependencyOf | | Resource | 이 엔티티와 같음, 보통 default | dependsOn, 그리고 역방향 dependencyOf |

spec.dependencyOf [선택]

리소스가 그 의존 대상이 되는 컴포넌트와 리소스에 대한 엔티티 참조 배열, 예: artist-lookup. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | Component | 이 엔티티와 같음, 보통 default | dependencyOf, 그리고 역방향 dependsOn | | Resource | 이 엔티티와 같음, 보통 default | dependencyOf, 그리고 역방향 dependsOn |

Kind: System

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | System |

System은 리소스와 컴포넌트의 모음이에요. 시스템은 하나 이상의 API를 노출하거나 소비할 수 있어요. 잠재적 소비자에게 모든 컴포넌트의 세부 사항을 지나치게 자세히 보지 않고도 노출된 기능에 대한 통찰력을 주는 추상화 수준으로 간주돼요. 이는 또한 소유 팀이 게시된 아티팩트와 API를 결정할 여지를 줘요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: artist-engagement-portal
  description: Handy tools to keep artists in the loop
spec:
  owner: artist-relations-team
  domain: artists

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 System과 같아요.

spec.owner [필수]

시스템 소유자에 대한 엔티티 참조, 예: artist-relations-team. 이 필드는 필수예요.

Backstage에서 시스템의 소유자는 시스템에 대한 궁극적인 책임을 지는 단일 엔티티(보통 팀)로, 그것을 개발하고 유지보수할 권한과 역량을 가져요. 무언가 잘못되거나 기능 요청이 있을 때 연락할 대상이 바로 그 사람들이에요. 이 필드의 주 용도는 Backstage에서 표시용으로, 카탈로그 항목을 보는 사람들이 이 시스템이 누구 것인지 알 수 있게 하는 것이에요. 런타임 시스템에서 권한을 할당하는 등의 자동화 프로세스에 사용해서는 안 돼요. 시스템을 개발하거나 만지는 다른 사람들이 있을 수 있지만, 궁극적인 소유자는 항상 한 명이에요.

| kind | Default namespace | Generated relation type | | Group (default), User | 이 엔티티와 같음, 보통 default | ownedBy, 그리고 역방향 ownerOf |

spec.domain [선택]

시스템이 속한 도메인에 대한 엔티티 참조, 예: artists. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | Domain (default) | 이 엔티티와 같음, 보통 default | partOf, 그리고 역방향 hasPart |

spec.type [선택]

시스템의 유형이에요. 현재 이 필드에 강제되는 값 집합은 없어서, 카탈로그 계층 구조와 맞는 명명 체계를 고르는 것은 도입 조직에 달려 있어요. 이 필드는 선택 사항이에요.

이 필드의 몇 가지 일반적인 값은 다음과 같을 수 있어요.

  • product

  • service

  • feature-set

Kind: Domain

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | Domain |

Domain은 용어, 도메인 모델, 비즈니스 목적, 또는 문서를 공유하는 시스템들의 모음을 그룹화해요. 즉 경계 컨텍스트(bounded context)를 형성해요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: artists
  description: Everything about artists
spec:
  owner: artist-relations-team
  subdomainOf: audio-domain

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 Domain과 같아요.

spec.owner [필수]

도메인 소유자에 대한 엔티티 참조, 예: artist-relations-team. 이 필드는 필수예요.

Backstage에서 도메인의 소유자는 도메인에 대한 궁극적인 책임을 지는 단일 엔티티(보통 팀)로, 그것을 개발하고 유지보수할 권한과 역량을 가져요. 무언가 잘못되거나 기능 요청이 있을 때 연락할 대상이 바로 그 사람들이에요. 이 필드의 주 용도는 Backstage에서 표시용으로, 카탈로그 항목을 보는 사람들이 이 도메인이 누구 것인지 알 수 있게 하는 것이에요. 런타임 시스템에서 권한을 할당하는 등의 자동화 프로세스에 사용해서는 안 돼요. 도메인을 개발하거나 만지는 다른 사람들이 있을 수 있지만, 궁극적인 소유자는 항상 한 명이에요.

| kind | Default namespace | Generated relation type | | Group (default), User | 이 엔티티와 같음, 보통 default | ownedBy, 그리고 역방향 ownerOf |

spec.subdomainOf [선택]

도메인이 그 일부가 되는 다른 도메인에 대한 엔티티 참조, 예: audio. 이 필드는 선택 사항이에요.

| kind | Default namespace | Generated relation type | | Domain (default) | 이 엔티티와 같음, 보통 default | partOf, 그리고 역방향 hasPart |

spec.type [선택]

도메인의 유형이에요. 현재 이 필드에 강제되는 값 집합은 없어서, 카탈로그 계층 구조와 맞는 명명 체계를 고르는 것은 도입 조직에 달려 있어요. 이 필드는 선택 사항이에요.

이 필드의 몇 가지 일반적인 값은 다음과 같을 수 있어요.

  • product-area

  • product-group

  • bundle

Kind: Location

다음 엔티티 kind를 설명해요.

| Field | Value | | apiVersion | backstage.io/v1alpha1 | | kind | Location |

Location은 카탈로그 데이터를 찾아볼 다른 장소를 가리키는 마커예요.

이 kind의 descriptor 파일은 다음과 같을 수 있어요.

apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: org-data
spec:
  type: url
  targets:
    - http://github.com/myorg/myproject/org-data-dump/catalog-info-staff.yaml
    - http://github.com/myorg/myproject/org-data-dump/catalog-info-consultants.yaml

공통 envelope metadata 형태에 더해, 이 kind는 다음과 같은 구조를 가져요.

apiVersion과 kind [필수]

각각 정확히 backstage.io/v1alpha1과 Location과 같아요.

spec [필수]

spec 필드는 필수예요. 최소 spec은 빈 객체여야 해요.

spec.type [선택]

spec에 지정된 대상들에 공통인 단일 location 유형이에요. 생략하면 원래 엔티티 데이터를 읽은 location 유형에서 상속돼요. 예를 들어 url 유형의 location을 읽었을 때 결과로 spec.type이 없는 Location kind 엔티티가 나온다면, 그 엔티티에 있는 참조 대상들도 암묵적으로 url 유형이 돼요. 이는 디렉터리 구조에서 상대 대상 경로(아래 참조)를 이용해 것들의 계층을 정의할 수 있어서 유용한데, 디스크의 file location에서 로컬로 소비하든 VCS에 업로드되든 상관없이 동작해요.

spec.target [선택]

문자열 형태의 단일 대상이에요. (유형에 따라) 절대 경로/URL일 수도 있고, ./details/catalog-info.yaml 같은 상대 경로일 수도 있어요. 상대 경로는 이 Location 엔티티 자신의 위치를 기준으로 해석돼요.

spec.targets [선택]

문자열 형태의 대상 목록이에요. 모두 (유형에 따라) 절대 경로/URL일 수도 있고, ./details/catalog-info.yaml 같은 상대 경로일 수도 있어요. 상대 경로는 이 Location 엔티티 자신의 위치를 기준으로 해석돼요.

spec.presence [선택]

location의 대상이 존재해야 하는지 여부를 설명해요. 지정하지 않으면 'required'로 기본 설정되고, 'optional'일 수도 있어요.

더 알아보기 (Learn more)