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

콜레이터

원문 보기 위키 갱신

콜레이터 (Collators)

Backstage에는 Catalog와 TechDocs용 콜레이터 2개가 기본 제공돼요. Backstage 커뮤니티에서 만든 콜레이터도 있어요!

출처: 문서

본문

Backstage에는 Catalog와 TechDocs용 콜레이터 2개가 기본 제공돼요. Backstage 커뮤니티에서 만든 콜레이터도 있어요!

Catalog

Catalog 콜레이터는 Catalog에 있는 모든 엔티티를 인덱싱해요. 기본으로 설치되지만, 필요하다면 수동으로 추가하는 방법은 다음과 같아요.

먼저 플러그인을 백엔드 앱에 추가해요.

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugin-search-backend-module-catalog

그런 다음 다음 줄을 추가해요.

packages/backend/src/index.ts

const backend = createBackend();// Other plugins...// search pluginbackend.add(import('@backstage/plugin-search-backend'));backend.add(import('@backstage/plugin-search-backend-module-catalog'));backend.start();

Catalog 콜레이터 구성하기

다음 섹션에서는 이 콜레이터에 사용할 수 있는 구성 옵션을 설명해요.

스케줄링

Catalog 콜레이터의 기본 스케줄은 10분마다 실행하는 것이에요. 구성에 직접 스케줄을 추가해서 나만의 스케줄을 제공할 수도 있어요.

search:  collators:    catalog:      schedule: # same options as in SchedulerServiceTaskScheduleDefinition        # supports cron, ISO duration, "human duration" as used in code        initialDelay: { seconds: 90 }        # supports cron, ISO duration, "human duration" as used in code        frequency: { hours: 6 }        # supports ISO duration, "human duration" as used in code        timeout: { minutes: 3 }

필터링

Catalog에서 특정 엔티티 하위 집합만 콜레이트하고 싶을 수 있어요. 이는 filter 구성 옵션으로 처리할 수 있어요. 기본 예시는 다음과 같아요.

search:  collators:    catalog:      filter:        kind: ['component', 'api']        spec.lifecycle: production

위 예시는 kind가 component 또는 api이면서 spec.lifecycle이 production인 엔티티만 콜레이트해요.

다음과 같이 더 고급 필터도 적용할 수 있어요.

search:  collators:    catalog:      filter:        - kind: ['API']          spec.type: openapi        - kind: ['Component']          spec.lifecycle: experimental

이 예시에서는 kind가 api이면서 spec.type이 openapi인 모든 엔티티를 콜레이트하거나, kind가 component이면서 spec.lifecycle이 experimental인 모든 엔티티를 콜레이트해요.

:::tip 필터 구성은 EntityFilterQuery 구문을 사용해 구현돼요. EntityFilterQuery에 대한 참조 문서에 더 자세한 내용이 있어요. :::

TechDocs

TechDocs 콜레이터는 Catalog에 있는 모든 TechDocs를 인덱싱해요. 기본으로 설치되지만, 필요하다면 수동으로 추가하는 방법은 다음과 같아요.

먼저 플러그인을 백엔드 앱에 추가해요.

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugin-search-backend-module-techdocs

그런 다음 다음 줄을 추가해요.

packages/backend/src/index.ts

const backend = createBackend();// Other plugins...// search pluginbackend.add(import('@backstage/plugin-search-backend'));backend.add(import('@backstage/plugin-search-backend-module-techdocs'));backend.start();

TechDocs 콜레이터 구성하기

TechDocs 콜레이터의 기본 스케줄은 10분마다 실행하는 것이에요. 구성에 직접 스케줄을 추가해서 나만의 스케줄을 제공할 수도 있어요.

search:  collators:    techdocs:      schedule: # same options as in SchedulerServiceTaskScheduleDefinition        # supports cron, ISO duration, "human duration" as used in code        initialDelay: { seconds: 90 }        # supports cron, ISO duration, "human duration" as used in code        frequency: { hours: 6 }        # supports ISO duration, "human duration" as used in code        timeout: { minutes: 3 }

카탈로그 콜레이터를 통한 필터링

TechDocs 콜레이터는 기본적으로 metadata.annotations.backstage.io/techdocs-ref 어노테이션이 존재하는 카탈로그 엔티티를 필터링해요. 엔티티를 더 필터링하려면 techDocsCollatorEntityFilterExtensionPoint를 통해 두 가지 방법으로 처리할 수 있어요.

export const exampleCustomCatalogFiltering = createBackendModule({  pluginId: 'search',  moduleId: 'search-techdocs-collator-entity-filter',  register(reg) {    reg.registerInit({      deps: {        customCollatorFilter: techDocsCollatorEntityFilterExtensionPoint,      },      async init({ customCollatorFilter }) {        /* filtering by catalog params */        customCollatorFilter.setCustomCatalogApiFilters([          { kind: ['API', 'Component', ...] },          { metadata: ['...more filters'] },        ]);        /* filtering by a custom function */        customCollatorFilter.setEntityFilterFunction((entities: Entity[]) =>          entities.filter(            entity => entity.metadata?.annotations?.abc === 'xyz',          ),        );      },    });  },});

커뮤니티 콜레이터

Backstage 커뮤니티에서 제공하는 알려진 검색 콜레이터는 다음과 같아요.

  • @backstage-community/plugin-search-backend-module-explore: Explore 플러그인의 콘텐츠를 인덱싱해요.

  • @backstage/plugin-search-backend-module-stack-overflow-collator: Stack Overflow의 콘텐츠를 인덱싱해요.

  • @backstage-community/search-backend-module-adr: ADR 플러그인의 콘텐츠를 인덱싱해요.

  • @backstage-community/plugin-search-backend-module-announcements: Announcements 플러그인의 콘텐츠를 인덱싱해요.

  • @backstage-community/plugin-search-backend-module-azure-devops: Azure DevOps의 위키 문서를 인덱싱해요.

  • @backstage-community/plugin-search-backend-module-confluence-collator: Confluence의 콘텐츠를 인덱싱해요.

  • @backstage-community/plugin-search-backend-module-github-discussions: GitHub Discussions의 콘텐츠를 인덱싱해요.

  • @backstage-community/plugin-search-backend-module-report-portal: ReportPortal의 콘텐츠를 인덱싱해요.

사용자 지정 콜레이터

나만의 콜레이터를 만드는 방법을 알아보려면 '사용자 지정 콜레이터 작성' 가이드를 참고하세요.

더 알아보기 (Learn more)