CBA — Backstage 인증 어소시에이트 · Backstage 와 개발자 포털 · 이론

Backstage 는 왜 제품이 아니라 프레임워크인가

한 줄 요약

Backstage 는 Spotify 가 사내에서 쓰던 개발자 포털을 2020 년에 오픈소스로 공개하고 CNCF 에 기증한 것입니다(2022 년 인큐베이팅 승격). 그리고 설치해서 바로 쓰는 제품이 아니라, 여러분의 포털을 짓기 위한 프레임워크 입니다. 이 차이를 모르고 도입하면 반드시 실패합니다.

왜 이게 필요했나

어느 정도 규모가 된 조직에 다음 질문을 던져 보면 대개 답이 안 나옵니다.

우리 회사에 서비스가 몇 개인가?
이 서비스의 주인은 누구인가? 새벽 3 시에 누구를 깨워야 하나?
이 API 를 누가 쓰고 있나? 지금 없애면 뭐가 깨지나?
새로 온 개발자가 첫 배포를 하려면 무엇을 읽어야 하나?

답이 없는 이유는 정보가 없어서가 아니라 흩어져 있어서 입니다. 소유자는 위키에, 배포는 CI 대시보드에, 의존 관계는 누군가의 머릿속에, 문서는 3 년 전 컨플루언스에 있습니다. 각각은 최신인데 합치면 아무 그림도 안 나옵니다.

Backstage 의 답은 이렇습니다. 소프트웨어 카탈로그를 만들고, 그 카탈로그가 코드 저장소에서 자동으로 채워지게 한다. 소유권 정보가 코드 옆(catalog-info.yaml)에 살면 코드를 옮길 때 함께 옮겨지고, 리뷰를 거치며, 오래된 채로 남을 확률이 크게 줄어듭니다.

어떻게 동작하나

세 개의 기둥

Backstage 를 처음 볼 때 알아야 할 것은 셋입니다.

1. 소프트웨어 카탈로그(Software Catalog) — 우리가 가진 모든 것의 목록과 그 관계. Backstage 의 심장입니다.
2. 소프트웨어 템플릿(Software Templates / 스캐폴더) — 새 서비스를 골든 패스로 만들어 내는 장치.
3. TechDocs — 코드 옆에 사는 마크다운 문서를 포털에서 렌더해 보여 주는 기능.

여기에 플러그인 생태계가 붙습니다. Kubernetes, CI, 온콜, 비용, 보안 스캐너 등 각 도구의 정보를 엔티티 페이지 안으로 끌어옵니다. 이게 포털의 핵심 가치입니다 — 도구를 하나로 합치는 게 아니라, 엔티티(서비스)를 중심으로 정보를 모아 보여 주는 것 입니다.

프론트엔드 플러그인과 백엔드 플러그인

Backstage 는 두 개의 앱으로 나뉩니다.

| | 프론트엔드 | 백엔드 |
| --- | --- | --- |
| 무엇 | React 애플리케이션 | Node.js 서비스 |
| 플러그인이 하는 일 | 페이지·탭·카드·아이콘 제공 | API 엔드포인트, 데이터 수집, 외부 시스템 인증 |
| 예 | 엔티티 페이지의 "Kubernetes" 탭 | 클러스터에 질의해 워크로드를 가져오는 서비스 |
| 왜 나뉘나 | 브라우저에 자격증명을 두면 안 되니까 | 토큰·시크릿은 서버에만 |

이 분리가 보안상 중요합니다. 프론트엔드 플러그인이 직접 쿠버네티스 API 를 부르면 사용자 브라우저에 클러스터 자격증명이 필요합니다. 그래서 백엔드 플러그인이 대신 부르고, 프론트엔드는 백엔드의 엔드포인트만 호출합니다.

왜 제품이 아닌가

Backstage 를 쓰려면 npx @backstage/create-app 으로 여러분 소유의 앱 소스 트리 를 만듭니다. 그 뒤로는 그게 여러분의 코드입니다. 플러그인을 추가하려면 코드를 고치고, 빌드하고, 배포합니다. 업그레이드도 여러분의 몫입니다.

이 선택의 장단이 분명합니다.

좋은 점 — 조직에 맞게 무엇이든 바꿀 수 있습니다. 사내 전용 플러그인을 만들어 붙일 수 있고, 정보 구조를 우리 조직 언어로 정의할 수 있습니다.
나쁜 점 — 유지보수 주체가 필요합니다. TypeScript/React 를 다룰 수 있는 팀이 상시 붙어 있어야 하고, 업그레이드 부담이 계속 발생합니다.

그래서 CBA 시험에서도 "Backstage 를 설치하면 바로 쓸 수 있는 포털이 생기는가?" 류의 문항이 나오면 답은 아니오입니다. 도입 결정은 기술 선택이 아니라 인력 배치 결정 입니다. 이 프레임워크를 제품처럼 다룰 팀이 없으면, 6 개월 뒤 아무도 업그레이드하지 않는 방치된 포털이 하나 더 생깁니다.

현장에서 만나는 모습

저자의 7 노드 홈랩만 봐도 카탈로그가 왜 필요한지 보입니다. 한 클러스터 안에 Cilium(CNI), MetalLB(L4 LB), Cilium Gateway API(L7), csi-driver-nfs(스토리지), GPU Operator(GPU 4 장), KubeVirt+CDI(가상화), CloudNativePG(DB), kube-prometheus-stack(관측), Gitea(10.0.0.200), Argo CD(10.0.0.201), Harbor(10.0.0.202), Grafana(10.0.0.203)가 올라가 있습니다. 각각에 사연이 있습니다 — Gateway API 는 CRD v1.6.1 이 필요했고, KubeVirt 는 containerDisk 경로에 결함이 있어 DataVolume 우회가 필요했습니다.

한 사람이 혼자 운영하는 홈랩인데도 이 목록과 사연을 기억해 두지 않으면 반년 뒤에 헤맵니다. 조직이면 말할 것도 없습니다. "무엇이 있고, 왜 그렇게 설정됐고, 누가 아는가" 를 사람 머리 밖에 두는 것 — 그게 카탈로그의 존재 이유입니다.

그리고 이 클러스터의 반복된 교훈인 "상태가 Ready 와 실제로 동작한다는 다른 명제" 도 포털 설계에 그대로 적용됩니다. 엔티티 페이지에 초록 배지 여러 개를 띄우는 것은 쉽습니다. 어려운 것은 그 배지가 실제 사용자 경험과 연결되어 있는가입니다. 포털은 정보를 모으는 도구이지, 모았다고 해서 그 정보가 참이 되지는 않습니다.

다음 퀴즈에서 확인할 것

이 모듈은 퀴즈로 마무리합니다. 다음 모듈에서 카탈로그의 엔티티 종류와 관계를 배우고, /root/cba-catalog/ 에 실제 catalog-info.yaml 세트를 직접 작성합니다. Backstage 자체는 실습 환경에 없으므로 엔티티 파일 작성과 그 소유권 정보를 클러스터 라벨로 표현하는 방식으로 다룹니다.