플랫폼 엔지니어링 06 - 개발자 포털과 서비스 카탈로그

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

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

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

포털이 하는 일

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

Backstage

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

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

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

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

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

플러그인

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

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

대안들

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

언제 필요한가

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

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

개발자 포털은 암묵지를 구조화되고 검색 가능하며 항상 최신 상태인 정보로 전환하는 역할을 한다. 제대로 구축하기는 쉽지 않지만, 성공하면 그 차이가 확연히 드러나는 것이다.

다음 포스트에서는 플랫폼을 제품처럼 다루는 이야기를 살펴본다.