클릭 몇 번으로 끝! Backstage 카탈로그 수동 등록(Manual Register) 완벽 가이드

안녕하세요, 플랫폼 엔지니어 여러분! 🛠️ 새로운 마이크로서비스를 만들었거나 기존 프로젝트를 Backstage에 통합하고 싶을 때, 가장 빠르고 확실한 방법은 무엇일까요?

자동 스캔 기능이 설정되어 있지 않더라도 걱정하지 마세요. Backstage는 사용자가 직접 엔터티(Entity)의 위치를 알려주는 수동 등록(Manual Registration) 방식을 지원합니다. 지금부터 그 단계를 하나씩 파헤쳐 보겠습니다!

---

1. 수동 등록이란 무엇인가요? 🤔

수동 등록은 개발자가 자신의 서비스 정의 파일(catalog-info.yaml)이 어디에 있는지 Backstage에게 직접 알려주는 행위입니다.

• 핵심 메커니즘: 파일의 URL(경로)을 등록합니다.
• 지원되는 소스: GitHub, GitLab, Bitbucket 등 소스 코드 호스팅 서비스에 업로드된 파일의 직접 링크를 사용합니다.

---

2. 준비물: catalog-info.yaml 📄

수동 등록을 하기 전, 반드시 프로젝트 저장소에 설정 파일이 존재해야 합니다. 이 파일이 없으면 Backstage는 등록할 정보를 읽어오지 못합니다.

# 예시: catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-manual-service
  description: 수동으로 등록한 멋진 서비스입니다.
spec:
  type: service
  owner: user:guest
  lifecycle: experimental

 

이 파일을 저장소(예: GitHub)에 Push한 후, 해당 파일의 브라우저 주소창 URL을 복사해 두세요! 🔗

---

3. 단계별 수동 등록 절차 (Step-by-Step) 🚶‍♂️

이제 실제 Backstage 화면에서 등록해 봅시다.

1단계: Catalog 메뉴 접속

왼쪽 사이드바에서 [Catalog] 메뉴를 클릭합니다.

2단계: "Create" 또는 "Register" 버튼 클릭

카탈로그 메인 화면 우측 상단에 있는 [Create] 버튼을 누르세요. 보통 이곳은 새로운 소프트웨어 템플릿을 만드는 곳이지만, 수동 등록 버튼도 함께 위치해 있습니다.

3단계: "Register Existing Component" 선택

화면 구석에 있는 [Register Existing Component] 버튼을 찾아서 클릭합니다. 이것이 바로 우리가 찾는 수동 등록 기능입니다! ✨

4단계: URL 입력 및 분석

복사해둔 catalog-info.yaml 파일의 URL을 입력창에 붙여넣습니다.

• Analyze: 버튼을 누르면 Backstage가 해당 경로에 파일이 있는지, 문법은 맞는지 미리 검사합니다.

5단계: 최종 확인 및 완료

검사가 통과되면 [Import]를 누릅니다. 이제 카탈로그 목록에서 방금 등록한 서비스를 확인할 수 있습니다! 🎉

---

4. 수동 등록의 장점과 주의사항 💡

장점 👍

• 즉시성: 자동 수집(Ingestion) 주기까지 기다릴 필요 없이 즉시 반영됩니다.
• 유연성: 특정 프로젝트만 선별적으로 카탈로그에 노출하고 싶을 때 유용합니다.
• 테스트 용이: 새로운 catalog-info.yaml 설정을 테스트할 때 가장 빠른 방법입니다.

주의사항 ⚠️

• URL 권한: Backstage 백엔드가 해당 URL(예: Private Repo)에 접근할 수 있는 권한(Token)이 설정되어 있어야 합니다.
• 중복 등록: 이미 등록된 URL을 다시 등록하려고 하면 에러가 발생할 수 있습니다.

---

5. 요약: 수동 등록의 핵심 3줄 정리 📝

1. 준비: 프로젝트 저장소에 catalog-info.yaml 파일을 푸시한다.
2. 복사: 해당 파일의 원본(Raw) URL 또는 브라우저 주소를 복사한다.
3. 등록: Backstage UI의 Register Existing Component 메뉴에서 URL을 입력하고 Import 한다.

---

🏁 마무리하며

Backstage 카탈로그에 내 발자취를 남기는 가장 직접적인 방법인 '수동 등록'에 대해 알아보았습니다. 처음에는 수동으로 등록하며 감을 익히고, 나중에 서비스가 많아지면 Entity Providers를 통한 자동 수집으로 확장해 나가는 것이 좋습니다. 🚀