Backstage에 대해 살펴봤던 지난 아티클을 기억하는가? 개발 조직의 IDP(내부 개발자 플랫폼) 생성을 도와주는 오픈소스 프레임워크이며 CNCF에서 적극 밀어주는 프로젝트라고 소개한 바 있다.
글로벌 IDP 시장의 대표적인 프로젝트이라고 해도, 우리 조직에 맞는 시스템이어야 도입하는 의미가 있다.
Software Catalog나 Software Template 기능이 조직에 정말 필요한지, TechDocs 기능이 조직 문화와 어울리는지 경험해봐야 알 수 있는 것이다.
그래서 이번 아티클에서는 Backstage 앱을 직접 로컬에 생성해서 살펴보는 실습을 진행해보려 한다. Backstage 앱을 구성하는 주요한 설정이나 소스코드도 짚어보겠다.
1. Backstage 앱을 호스트에 생성하기
Backstage 앱은 Node.js 환경(22버전 이상 권장)에서 생성할 수 있다. 앱 생성에 필요한 도구는 아래와 같다.
- git: 레파지토리 관리를 위해 필요
- npx: Node.js와 함께 설치되는 패키지 실행 도구
- yarn:
npm install --global yarn명령어로 설치 가능한 패키지 관리자
조직마다 요구되는 IDP가 다르므로 npx를 통해 생성된 Backstage 앱을 조직에 맞춰 커스터마이징 및 추가 개발이 필요할 수 있다. 그래서 Backstage를 IDP 개발용 프레임워크라고 하는 것이다.
이제 실습을 시작해보자. 로컬 터미널에서 아래 npx 명령어로 최신 버전의 Backstage 앱을 생성한다.
npx @backstage/create-app@latest
앱 생성 중에 프로젝트 이름을 설정하라고 뜬다. my-backstage로 지정하고 이어간다.
몇 분 정도 기다리면 앱이 성공적으로 생성되었다는 출력이 표시된다.
npx 명령어를 실행한 경로에 Backstage 앱 디렉토리가 생성되었다. Backstage 앱의 주요 구성은 아래와 같다.
my-backstage
├─ app-config.yaml
├─ catalog-info.yaml
├─ package.json
├─ examples
└─ packages
├─ app
└─ backend
app-config.yaml:- Backstage 앱의 설정(Configuration)을 관리하는 파일이다. Backstage 앱의 URL부터 Backend의 URL 및 포트번호, DB 연결 및 인증 설정 등이 포함된다.
catalog-info.yaml:- Backstage에서 관리하는 모든 요소를 카탈로그 엔티티(Catalog Entity)라고 부른다. 여기서 모든 요소란 조직이 개발하는 서비스와 라이브러리뿐만 아니라 DB, 조직 내 개발자, 그룹, 도메인 등을 포함한다.
- 그리고 이런 카탈로그 엔티티를 한 곳에 정리한 파일이 바로
catalog-info.yaml이다. - 여기서 모든 카탈로그 엔티티의 이름과 설명, 그리고 엔티티 간의 소유/소비/의존/계층/소속 관계를 정의한다.
- Backstage의 주요 기능인 Software Catalog가 바로 이 정의를 토대로 사용자에게 모든 카탈로그 엔티티의 관계를 웹 UI로 보여주는 것이다.
examples/:- Backstage 처음 실행 시 웹 UI에 보여줄 샘플 데이터를 모아둔 디렉토리
packages/:- yarn으로 관리되는 패키지가 위치하는 디렉토리
packages/app/:- Backstage의 프론트엔드 소스코드가 위치한 디렉토리
packages/backend/:- Backstage의 백엔드 소스코드가 위치한 디렉토리
Backstage 앱이 생성되었으니 실행해볼 차례다. 생성된 디렉토리로 이동한 다음 아래 yarn 명령어를 입력한다.
yarn start그럼 아래와 같이 app(프론트엔드)과 backend(백엔드)가 시작되었고 app-config.yaml 파일이 로드되었다는 안내가 나올 것이다.
이후 웹 브라우저가 자동으로 켜지면서 http://localhost:3000 주소로 접속한다. 우리 Backstage의 프론트엔드 서버에 접근한 것이다. 만약 웹브라우저가 자동으로 켜지지 않는다면 해당 주소로 직접 접속해보자.
Backstage 프론트엔드 서버에 접속하면 아래처럼 우리가 Guest 사용자라는 알림이 뜰 것이다. 아직 Backstage에서 인증 관련 작업을 하지 않아서 개발용으로 준비된 Guest 설정이 적용된 것이다. ENTER를 눌러 넘어가자.
그럼 위와 같이 우리가 생성해서 실행한 Backstage 앱의 Catalog 화면이 뜰 것이다. 왼쪽 사이드바에 API와 카탈로그 관계 그래프, TechDocs(Docs) 메뉴를 확인할 수 있다.
이제 로컬에서 Backstage 앱을 생성 후 실행하는 데에 성공했다. 하지만 Backstage는 IDP에 대한 정말 많은 것을 다루는 프레임워크이므로 여기서 끝이 아니다.
지금 당장 Backstage의 전부를 알아야 하는 것은 아니지만, 적어도 Backstage 앱이 현재 어떤 과정을 거쳐 무엇을 웹 UI로 보여주는지는 이해해야 한다.
그래서 방금 npx로 갓 생성된 Backstage 앱에서 눈여겨봐야 할 구성과 소스코드를 함께 살펴보겠다.
2. 우리가 유심히 살펴봐야 할 것들
Guest 모드 설정 위치
방금 전 웹 브라우저로 Backstage 앱에 처음 접속했을 때 Guest 사용자로 들어간 것을 기억하는가? 현재 우리 Backstage에서 인증 프로바이더로 Guest를 사용하고 있기 때문에 그렇다.
Backstage에서는 GitHub과 Google 같은 다양한 인증 프로바이더를 지원하고 있다. 하지만 이를 위해서는 추가 설정과 코드 수정이 필요하므로, Backstage 앱에 바로 접속하고 테스트해볼 수 있도록 미리 준비된 Guest 프로바이더가 초기 설정되어 있는 것이다.
주의
Guest 프로바이더는 개발 편의를 위해 제공된 것이므로 보안을 위해 프로덕션 환경에서는 반드시 비활성화해야 한다.
그렇다면 이 Guest 모드는 어디에 설정되어 있을까? 바로 Backstage 앱의 Configuration을 담당하는 app-config.yaml 파일이다. 실제 해당 파일의 코드 중 일부를 살펴보자.
...
auth:
# see https://backstage.io/docs/auth/ to learn about auth providers
providers:
# See https://backstage.io/docs/auth/guest/provider
guest: {}
...auth.providers 필드의 값으로 guest가 명시되어 있으므로 우리의 Backstage 앱은 Guest 프로바이더를 사용할 수 있는 것이다.
설정 파일만으로 웹 UI 상의 인증 관련 로직이 구현되지는 않는다. Backstage 앱이 Guest 프로바이더를 사용할 수 있는 것은 소스코드에도 관련 내용이 있기 때문이다.
Backstage의 packages/ 디렉토리에는 프론트엔드와 백엔드 소스코드가 저장되어있다고 했다.
백엔드 소스코드인 packages/backend/src/index.ts 파일에는 아래와 같은 내용이 있다.
...
backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
...바로 이 부분에서 Backstage의 백엔드가 Guest 프로바이더를 가져와 사용하는 것이다. 이를 바꿔서 이야기하자면, 다른 인증 프로바이더를 사용할 땐 위 부분들을 알맞게 수정해야 한다.
Backstage가 사용하는 DB
Backstage는 카탈로그 엔티티와 각 주요기능과 관련된 데이터를 DB에 저장한다. 그렇다면 지금 우리의 Backstage는 어떤 DB를 사용하고 있을까?
답은 app-config.yaml 파일에 있다. 해당 파일의 backend 필드 하위에는 아래와 같은 설정이 있다.
...
backend:
...
database:
client: better-sqlite3
connection: ':memory:'
...현재 Backstage는 better-sqlite3를 사용 중이다. Node.js 환경에서 빠르고 가볍게 사용할 수 있는 SQLite 라이브러리이며 별도의 DB 서버를 설치할 필요가 없다는 것이 장점이다.
아래 connection 필드의 값이 ':memory:'인 것이 보이는가? 이건 better-sqlite3가 하드디스크에 데이터를 저장하고 있지 않고 RAM(메모리)에서 동작하고 있다는 뜻이다.
즉, 지금 Backstage 앱이 동작하고 있을 때 저장되는 데이터들은 앱이 꺼지거나 재시작하면 모두 날아간다. 빠른 테스트를 위해 이런 초기 설정이 되어 있는 것이다.
만약 Backstage 앱을 실제 환경에서 사용하려면 별도의 DB 서버를 구축한 다음 위의 app-config.yaml 내용을 수정해야 한다. Backstage 공식문서는 PostgreSQL와 연동할 것을 권장하고 있다.
Catalog 페이지에서 만난 example-website의 정체
방금 전 Backstage 앱의 Catalog 페이지에서 우리는 example-website라는 컴포넌트를 마주쳤다. 이 컴포넌트는 아까 살펴본 것처럼 catalog-info.yaml 파일에 정의되어 있는 걸까?
사실 아니다. 현재 우리 Backstage의 루트 경로에 존재하는 catalog-info.yaml 파일에는 my-backstage이라는 이름의 컴포넌트가 정의되어 있다. 이렇게 차이가 존재하는 이유는 app-config.yaml의 아래 설정 때문이다.
...
catalog:
...
locations:
# Local example data, file locations are relative to the backend process, typically `packages/backend`
- type: file
target: ../../examples/entities.yaml
# Local example template
- type: file
target: ../../examples/template/template.yaml
rules:
- allow: [Template]
# Local example organizational data
- type: file
target: ../../examples/org.yaml
rules:
- allow: [User, Group]
...아까 Backstage의 구성요소 중 examples 디렉토리를 웹 UI에 보여줄 샘플 데이터가 위치하는 곳이라고 했었다. 위 locations 필드 설정으로 인해 루트 경로의 catalog-info.yaml 파일에 정의된 것이 아닌, examples 디렉토리 내 샘플 파일에 정의된 카탈로그 엔티티가 Backstage 앱에 보이는 것이다.
Backstage의 catalog-info.yaml 파일의 카탈로그 엔티티가 정상 표시되려면 위 내용을 수정해야 한다.
마무리
이번 실습 가이드에서는 로컬에서 Backstage 앱을 생성하고 테스트해봤다. Backstage의 초기 설정 중 눈여겨봐야 할 것들도 살펴봤다.
다음 아티클에서는 Backstage를 데모 단계가 아닌 개발 단계로 넘어가 3가지 핵심 기능을 직접 사용해보는 실습을 진행해보겠다.