"그거 어디서 찾지?" 문제

조직의 규모가 커지면 정보가 흩어지기 시작한다. 문서는 Confluence에, 런북은 Google Docs에, API 스펙은 Swagger에 분산되어 있고, 배포 정보는 2023년 이후로 아무도 업데이트하지 않은 위키에 남아 있는 경우가 많다. 가장 중요한 지식은 결국 특정 담당자의 머릿속에만 존재하게 된다.

이런 환경에서 신규 개발자가 합류하면 첫 2주를 무엇이 어디에 있는지 파악하는 데 소비하게 된다. 개발자 포털은 이 문제에 대한 체계적인 답이다. 모든 서비스, 도구, 문서에 하나의 접근 지점을 제공한다.

포털이 하는 일

개발자 포털은 플랫폼의 정문에 해당한다. 서비스 목록, 담당자 정보, 문서, 상태, 도구를 한 곳에서 확인할 수 있게 해주는 것이 핵심이다. 과거에는 스무 군데를 돌아다녀야 찾을 수 있던 정보를 한 곳으로 모으는 역할을 수행하는 셈이다.

가치를 가장 쉽게 느낄 수 있는 순간은 "처음 보는 서비스를 이해해야 할 때"다. 예를 들어 신규 입사자가 결제 서비스를 맡게 되었다고 하자. 필요한 정보는 생각보다 많다. 레포지토리는 어디 있는지, 현재 오너는 누구인지, 운영 대시보드는 무엇인지, 배포 파이프라인은 어디서 확인하는지, 장애가 났을 때 봐야 할 런북은 무엇인지, 연관된 업스트림과 다운스트림 서비스는 어떤 것인지까지 알아야 한다. 포털이 없으면 이 정보를 슬랙, 위키, 저장소 README, 사람 기억에서 하나씩 수집해야 한다. 포털이 잘 구축되어 있으면 이 흐름이 "서비스 페이지 하나 열기"로 바뀐다.

서비스 카탈로그에 무엇이 들어가야 하나

좋은 서비스 카탈로그는 단순한 목록이 아니다. 최소한 다음 정보는 안정적으로 제공해야 한다.

  • 서비스 이름과 설명
  • 소유 팀과 담당자
  • 소스 저장소와 배포 파이프라인
  • 운영 대시보드와 알림 채널
  • API 문서와 런북
  • 사용하는 데이터 저장소나 외부 의존성
  • 프로덕션, 스테이징 같은 운영 상태

핵심은 "찾을 수 있느냐"보다 "믿을 수 있느냐"다. 카탈로그가 자주 틀리면 사람들은 다시 슬랙 DM으로 돌아간다. 그래서 포털은 문서를 예쁘게 모아두는 도구가 아니라, 메타데이터를 지속적으로 최신 상태로 유지하는 운영 체계와 함께 가야 한다.

Backstage

Backstage는 Spotify가 내부적으로 개발하여 2020년에 오픈소스로 공개한 개발자 포털 프레임워크이다. 현재 가장 널리 채택되고 있지만, 완성된 제품이 아니라 각 조직의 필요에 맞게 커스터마이징하는 프레임워크라는 점을 이해해야 한다.

Backstage의 핵심 기능은 세 가지로 구성된다.

첫째는 서비스 카탈로그이다. 조직 내 모든 컴포넌트의 레지스트리 역할을 한다. 서비스, 라이브러리, API, 파이프라인 등을 등록하고, 각각의 소유권과 상태, 메타데이터를 추적할 수 있게 해준다.

둘째는 소프트웨어 템플릿이다. 템플릿을 선택하면 CI/CD, 모니터링, 문서가 미리 구성된 프로덕션 레디 스켈레톤을 받을 수 있다. 과거처럼 기존 레포지토리를 복사한 뒤 불필요한 부분을 삭제하는 방식으로 새 프로젝트를 시작할 필요가 없어지는 것이다.

셋째는 TechDocs이다. 레포지토리에 있는 Markdown 파일을 포털에서 바로 렌더링해주기 때문에, 문서가 코드 바로 옆에 위치하게 되어 내용이 실제 구현과 괴리되는 문제를 방지할 수 있다.

플러그인

Backstage의 진정한 강점은 플러그인 생태계에 있다. Kubernetes 가시성 확보, GitHub Actions나 Jenkins, ArgoCD를 통한 CI/CD 상태 확인, 클라우드 비용 모니터링, API 문서 통합, 인시던트 관리, 보안 스캔 등을 플러그인으로 추가할 수 있다.

모놀리식 도구를 구매하는 대신, 조직에 실제로 필요한 기능들을 조합하여 자체 포털을 구성할 수 있다는 점이 이 접근법의 장점인 것이다.

다만 플러그인이 많다고 좋은 포털이 되는 것은 아니다. 첫 화면이 온갖 위젯으로 가득 차 있는데 정작 "누가 이 서비스를 책임지는지"가 안 보인다면 실패한 설계다. 포털은 기능 전시장이 아니라, 개발자가 가장 자주 묻는 질문에 가장 짧은 경로로 답하는 인터페이스여야 한다.

대안들

포털모델적합한 경우
Backstage오픈소스, 셀프호스팅완전한 제어와 커스터마이징
PortSaaS직접 안 만들고 포털을 쓰고 싶을 때
CortexSaaS서비스 품질 스코어카드
OpsLevelSaaS소유권과 성숙도 추적

Backstage는 유연성이 가장 높지만 그만큼 엔지니어링 투자가 필요하다. SaaS 제품들은 커스터마이징의 폭을 줄이는 대신 빠른 도입이 가능하다는 장단점이 있는 것이다.

언제 필요한가

과연 모든 조직에 개발자 포털이 필요한가? 그렇지 않다. 서비스가 5개이고 개발자가 10명인 조직이라면 잘 정리된 README만으로도 충분하다.

하지만 서비스가 30개를 넘어서면서 소유권이 모호해지기 시작할 때, 온보딩 과정에서 컨텍스트 파악에만 일주일 이상이 소요될 때, 기존에 이미 존재하는 솔루션을 찾지 못해 중복 작업이 발생할 때, 이러한 고통이 실제로 느껴지는 시점이 포털 도입을 고려해야 할 때이다.

개발자 포털은 암묵지를 구조화되고 검색 가능하며 항상 최신 상태인 정보로 바꾸는 역할을 한다. 제대로 구축하기는 쉽지 않지만, 잘 만들어 놓으면 신규 입사자의 첫 주 경험, 장애 대응 속도, 서비스 소유권의 선명함 같은 지표에서 차이가 바로 드러난다.

다음 글에서는 플랫폼을 제품처럼 다루는 방식을 다룬다.